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Chapter 1 


Introduction 


SunCGI (Sun Computer Graphics Interface) provides access to low-level graphics device func- 
tions without the restrictions, benefits, or overhead of higher-level graphics packages such as 
SunCore. SunCGI is useful for two-dimensional graphics programs which do not require seg- 
mentation or transformations. The absence of segmentation from SunCGI makes drawing 
diagrams faster and simpler, but does not provide automatic picture regeneration. SunCGI pro- 
grams are usually smaller and more efficient than SunCore programs with similar functionality. 
In addition, SunCGI programs will run on all of Sun’s devices without explicitly specifying the 
device at compile time. Furthermore, SunCGI provides output primitives (for example, circles), 
attributes (for example, sophisticated pattern filling), and input primitives which are not offered 
by SunCore. 

SunCGI is Sun Microsystem’s interpretation of the March, 1984 working draft of the ANSI X3H3 
committee which is commissioned with designing the CGI standard 1 . The CGI standard is 
currently under development, and therefore, CGI has not been accepted by the X3H3 committee, 
ANSI, or the computer graphics community. Furthermore, only certain models within the CGI 
proposed standard are supported by SunCGI. Specifically SunCGI implements input option 
sets 1, 2, 3, 4, and 6 and output option sets 1 through 6 of the CGI standard. Furthermore, the 
user should be aware that CGI does not support three-dimensional output primitives. 

SunCGI does provides output primitives, attribute selection, and input device management, at a 
level which is close to the actual device driver; thus affording speed and flexibility not offered by 
higher-level graphics packages such as SunCore. SunCGI provides output primitives which 
are not provided by any of the other Sun graphics packages: for example disjoint polygons, cir- 
cles, ellipses, and cell arrays (which can be thought of as scaled and transformed pixel arrays). 
CGI also provides a larger vocabulary of attributes than SunCore. SunCGI also provides facili- 
ties for explicitly binding virtual input devices to physical input devices as well as explicit 
management of an event queue. 


1.1. Notations Used in this Manual 

Within the text of this manual, a typewriter font is used to represent function names and 
types. For example, append_text is the name of a function; Cint is the name of a type. 
The formal definitions of functions and arguments are printed in the typewriter font so 
that they resemble code as typed at a terminal. 

1 Both the CGI standard and Sun’s interpretation of it are subject to change. 
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Italic font is used to indicate an internal state of SunCGI. Internal states of SunCGI are not 
explicitly enumerated, but their definition should be obvious from their names (for example, 
current font). Internal states are distinguishable from function arguments in that they do not 
use the underscore (_) character. 

Italics are also used in the conventional manner (that is, to accentuate important words and 
phrases). Boldface is used for the names of Sun software packages such as SunCGI and Sun- 
Core. 

In examples of what a user types at a terminal, a bold typewriter font is used to 
represent what the user types, and the typewriter font represents what the software 
displays in response. 


1.2. Using SunCGI 

To link SunCGI with your application program, put the following line in your Makefile: 

cc testl.o -lcgi -lsunwindow -lpixrect -lm 

where testl.o is the name of the application program. Similarly, if your application program uses 
other libraries, they must also be included in the Makefile line. 

SunCGI uses a variety of structures and enumerated types. These types are defined in Appen- 
dix C. You should include the files <cgitypes.h>, and <cgiconstants.h> to provide the neces- 
sary type definitions and constants for your application program. 

All SunCGI functions can be called by one of two names: the expanded name or the C- 
language binding name. The expanded name is the first name provided in the function descrip- 
tion section, whereas the C-language binding name is specified in parenthesis. You must include 
the file <cgicbind.h> in your application program if you want to use the C-language binding 
name. The C-language binding names are an attempt to anticipate the C-language binding of 
CGI. However, no C-language binding has been included in the CGI standard, and the SunCGI 
binding is inspired by the C-language binding of GKS. 

As a final note, do not name any user-defined function or variable starting with the letters _cgi 
because doing so may disrupt the internal workings of SunCGI. 

FORTRAN programmers can access SunCGI functions by using the include file in cgidefs77.h 
and using the / usr/lib/libcgi77.a library to link with. Details of the FORTRAN interface to 
SunCGI are provided in appendix G. 


1.3. Overview of SunCGI 

This section provides an overview of the substance of the SunCGI manual. The four major sec- 
tions of the manual (which correspond to chapters) are: 

1) view surface initialization and termination (control), 

2) output primitives, 

3) attributes, and 

4) input. 

The overview of these chapters contains a brief introduction to the basic concepts of CGI. The 
appendices at the end of this manual provide quick reference tables and descriptions of the inter- 
faces between SunCGI and 
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1) Pixwisss and 

2) FORTRAN. 

1.3.1. Control (Initialization and Termination) 

The chapter on control describes functions for 

1) initializing and terminating the entire SimCGI package and individual view surfaces, 

2) defining the coordinate systems, 

3) interface negotiation, and 

4) signal trapping. 

The first section of the control chapter describes functions for opening and closing view surfaces 
(which are either windows or screens). SunCGI provides facilities for writing primitives to mul- 
tiple view surfaces. Output primitives can be written to a selected subset of the open view sur- 
faces by using the activate and deactivate commands (which turn a view surface on or off 
without closing the view surface). The functions discussed in the control chapter also define the 
range of normalized device coordinates (VDC Space) and device coordinates (screen space). The 
coordinates of most SunCGI functions are expressed in terms of VDC Space. The limits of both 
VDC Space and screen space can be defined by the application program. 

If you are attempting to run an application program developed on another vendor’s version of 
CGI, negotiation functions are provided which describe the capabilities of SunCGI. The applies 
tion program can use the information obtained by using the negotiation functions to call 
appropriate functions in SunCGI to make the application program run correctly. Finally, the 
control chapter describes SunCGI’s option for trapping SIGWINCH signals (generated by manipu- 
lating the window which the application program is using). 


1.3.2. Output 

SunCGI provides functions for drawing geometrical output primitives (for example, polygons, 
circles, and ellipses) as well as functions for performing raster operations. The coordinates of 
output primitives are specified in VDC Space (with the exception of some raster functions). 
Geometrical output primitives include rectangles, polymarkers circular and elliptical arcs in 
addition to those mentioned in the previous sentence. Geometrical output primitives are affected 
by attributes described in the following chapter (such as fill style and line width). All output 
primitives are affected by the drawing mode which determines how an output primitives is 
affected by pixels which have been previously drawn on the screen. 


1.3.3. Attributes 

Attributes functions control the appearance of output primitives. Attributes can be set individu- 
ally, or in groups which are called bundles. The use of most attributes is fairly straightforward; 
however, the options available for filling geometrical output primitives requires a word of expla- 
nation. Geometrical output primitives can be filled with textures called hatches or patterns. 
Hatches are simply arrays of color values with each element of the array corresponding to a 
pixel. Patterns are arrays of color values which can be scaled and translated. 
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1.3.4 . Input 

SunCGI offers a standard interface for receiving input from the mouse and the keyboard. The 
CGI input model is based on the concept of logical input devices such as LOCATORS, 
VALUATORS, and STROKES. Logical input devices are bound to physical devices (such as mouse 
buttons) called triggers. Triggers may be associated with logical input devices by the application 
program. Each logical input device has an associated measure (for example, the measure of a 
LOCATOR device is the mouse position on the screen). Each logical input device also has a state 
which determines how a device handles input. Each logical input device can be in one of five 
states: 

1) RELEASED (uninitialized), 

2) NO_EVENTS (initialized but unable to receive input), 

3) REQUEST_EVENT (wait for one event), 

4) RESPONDJSVENT (report one event asynchronously), and 

5) QUEUE_EVENT (put each event at the end of the event queue). 

1.3.5 . Programming Tips 

For novice C-language users, the syntax of SunCGI may pose some initial difficulties. When a 
pointer is specified as an argument to a SunCGI function, SunCGI usually expects space to be 
allocated by the application program and the function argument to be preceded by an amper- 
sand (&). SunCGI uses many enumerated types. These types are printed by the printf func- 
tion as integers. If you want to print out these values in English, you should use the enumerated 
types as indices into a character array which contains appropriate English equivalents of the 
enumerated types. Finally, if you are a novice programmer, begin by copying the example pro- 
gram in the example program appendix and develop your application program from this example. 
Further help can be obtained by referring to the tables at the end of the appendix specifying 
error messages. These tables list commonly encountered problems and how to solve them. 


1.3.6 . Appendices 

The first five appendices are provided as an informational reference which may make SunCGI 
easier to understand. This information will probably be particularly useful to novice users. The 
last two appendices describe the interfaces: 

1. between SunCGI and Pixwins (the SunWindow System) and 

2. betweenSunCGI and the FORTRAN programming language. 


1.8. 6.1. Reference Appendices 

The first appendix explains the difference between SunCGI and SunCore. The next appendix 
lists the ANSI CGI standard functions which are not implemented by SunCGI and the SunCGI 
functions which are not part of the ANSI CGI standard. The third appendix provides the type 
definitions used by the SunCGI functions. The fourth appendix lists the error messages and 
possible strategies for eliminating them. This appendix also lists possible causes of simple run- 
time errors. Finally, the fifth appendix describes a sample program. 
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1.3. 6. 2. Description of Interfaces to SunCGI 

The final two appendices describe the interfaces between SunCGI and other Sun software 
packages: Pixwins and FORTRAN. The first of the two interface appendices explains how to call 
SunCGI from application programs written on top of Pixwins. This interface allows SunCGI 
to write output primitives in different pixwins using different attributes. This interface is useful 
for application programs which wish to control different areas of the view surface independently. 
The final appendix describes the interface to the FORTRAN programming language. The behavior 
of each SunCGI function is the same in both C and FORTRAN. 


1.4. References 

1) ANSI X3H3 Technical Committee, 1984, ‘Graphics Kernel System dpANS’, ACM SIG- 
GRAPH, February 1984, ACM, New York. 

2) ANSI X3H3 Technical Committee, 1984, ‘Virtual Device Interface dpANS’, X3H3 84/45, 
March 1984, ANSI, New York. 
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Chapter 2 


Initializing (and Terminating) SunCGI 


2.1. View Surface Selection And Initialization 

No functions for initializing and terminating devices are provided in the current CGI standard. 
Therefore, six nonstandard functions open_cgi, close_cgi, open.vws, close_vws, 
activate_vws, and deactivate_vws are included in SunCGI. open_cgi and 
close_cgi initialize and terminate the operation of the SunCGI package. A view surface is 
initialized by calling open_vws. SunCGI is capable of handling more than one view surface at 
once. However, output primitives are not displayed unless a view surface is activated. 

A view surface is automatically activated when it is opened. However, a view surface can be 
deactivated (with the deactivate_vws function) when the output stream is not intended to 
appear on all view surfaces. Subsequent calls to SunCGI output functions will not apply to 
deactivated view surfaces 2 until activate_vws is called again (see the following example). 


2 However, inputs can be received on deactivated view surfaces. 
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main () 

{ 

Cvwsurf devicel, devic©2; /* declarations */ 

Cint namol , nam©2 ; 

Ccoor bot, top, center; 

Cint radius; 

/* values of arguments are assumed to be set by you */ 


open_cgi(); /* start cgi */ 

NORMAL_VWSURF (devicel, PIXWINDD) ; /* black-and-white view surface */ 
open_vws (&namel , &devicel) ; /* open device number 1 */ 

NORMAL_VWSURF (device2 , CG1DD) ; /* color view surface & / 


open_vws (&name2 , &device2) ; /* 
rectangle (&bot, &top) ; /* 
deactivate_vws (name2) ; /* 
circle (^center, radius) ; /* 
activate_vws (name2) ; /* 
circle (^center, 2 *radius) ; /* 
close_vws (namel) ; /* 
close_vws (nam©2) ; /* 
close_cgi () ; /* 

> 


open device number 2 */ 

draw a rectangle on both devices */ 

deactivate device number 2 */ 

draw a circle on device no. 1 only */ 

activate device number 2 */ 

draw a circle on both devices */ 

close device number 1 */ 

close device number 2 */ 

close cgi */ 


2,1.1. open_cgi fCopencgij 

Cerror open_cgi() 

open_cgi initializes the state of SunCGI to CGOP (CGi OPen). open_cgi does not initial- 
ize input devices but does initialize the event queue. No other CGI functions can be used without 
generating an error if open__cgi has not been called. 

ERRORS: 

1 ENOTCGCL CGI not in proper state: CGI shall be in state CGCL. 

Errors are reported in SunCGI by setting the return value of the function to a nonzero result 
and echoing an error message and number on the terminal. However, error trapping can be con- 
trolled by the set_error_warning_mask function. An explanation of each error message 
(and suggestions for how to eliminate them) is presented in Appendix D. 


2-2 


Revision A of 15 May 1985 



SunCGI Reference Manual 


Initializing (and Terminating) SunCGI 


Table 2-1: SunCGI Default States 


State 

Value 

Range of VDC Space 

(0—32767 in both X and Y directions) 

Clip Indicator 

ON 

Clip Rectangle 

(Range of VDC Space) 

Error Warning Mask 

INTERRUPT 

Input Devices 

(Uninitialized) 

Input Queue 

EMPTY 

Trigger Associations 

(Defaults specific values listed in Table 5-4) 

Echo Modes 

(Device specific values listed in Table 5-5) 


Some of the entries discussed in Table 2-1 may be unfamiliar to you at this time. However, all of 
these concepts are explained in the course of this chapter. Further, each of these concepts are 
referenced in the index. 


2.1.2 . open_vws fCopenvws^ 

Cerror open_vws (name, devdd) 

Cint *name; /* name assigned to cgi view surface */ 

Cvwsurf *devdd; /* view surface descriptor */ 

open_vws initializes a view surface. The list of available view surfaces is described below in 
Table 2-2. open.vws initializes the attributes to their default values (listed in Table 2-3). The 
returned argument name is the identifier which is used to refer this view surface in other 
SunCGI functions. If you want to reinitialize the state of the view surface without reopening it, 
you should use the hard_reset function. 

More than one view surface can be open at one time. Output primitives are displayed on all 
active view surfaces (view surfaces must be opened before they are activated). However, input 
is only echoed on the view surface which is pointed to by the mouse. You must set the view sur- 
face type by assigning the dd element of the devdd argument to the name of the appropriate dev- 
ice driver as in this example 3 : 

Cvwsurf device; 

NORMAL_VWSURF (device, BW2DD) ; /* black-and-white view surface */ 
open_vws (finame, & dev ice) ; 


8 Notice that when SunCGI specifies a pointer it usually requires that the argument is prefaced by an & 
character when the argument is actually used. 
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The N ORMAL_VW SURF macro initializes the dd element of the Cvwsurf structure and guarantees 
that the view surface will be opened in the normal fashion. However, if you want to open a win- 
dow with some nonstandard parameters, or open a second window from a graphics tool you 
should read the following paragraphs. If you want to use an existing pixwin then you should skip 
the following paragraphs and read Appendix F instead. 

If the view surface of the specified type has been previously initialized and the type of view sur- 
face is a window (PIXWINDD or CGPIXWINDD), a CGI tool (a window with the name CGI Tool) 
is opened. You may also define other characteristics of the view surface by setting the other ele- 
ments of the of the devdd argument (which is of type Cvwsurf). 

typed© f struct { 

char screenname [DEVNAME SIZE] ; /* physical screen */ 
char windowname [DEVNAME SIZE] ; /* window */ 

int windowfd; /* window file descriptor V 

int retained; /* retained flag */ 

int dd; /* device */ 

int cmapsize; /* color map size */ 

char cmapname [DEVNAME SIZE] ; /* color map name */ 

int flags; /* new flag */ 

char **ptr; /* CGI tool descriptor */ 

} Cvwsurf; 

The elements screenname and windowname specify alternate screens (for example, / dev/cgoneO) 
or alternate window (for example, /dev/winlO). If these elements are left blank, the current 
screen and the current window are used, unless the dd field implicitly specifies a device (for 
example CG1DD). The element windowfd is the window file descriptor for the current device. 
The current implementation of SunCGI ignores this element. 

If the element retained is nonzero, then the view surface created by open_vws has a retained 
window associated with it (that is, if the window is covered-up by another window and then 
revealed, the picture present before the window was covered-up will be redisplayed. 

By default the window created by open_vws is non-retained. That is, if the window is 
covered-up and then revealed the covered-portion will be redisplayed as white. However, draw- 
ing in non-retained windows is twice as fast as drawing in retained windows, so the choice of 
which type of view surface to open should be carefully considered. 

The dd element specifies the view surface type. The cmapsize and the cmapname elements 
determine the size and the name of the colormap. No colormap is enabled for black-and-white 
devices. The colormap determines the mapping between color indices and red, green, and blue 
values. If the colormap specified by the cmapname element of the devdd argument is the same as 
a colormap segment which already exists, then the colormap segment is shared. Refer to the 
Programmers 7 Reference Manual for Sun Windows for more information about colormaps. 

When the flags element is nonzero, no attempt is made to take over the current graphics 
subwindow (if one exists). If this flag is set or the graphics subwindow has already been taken 
over by SueCGI, then a CGI Tool (a window with the name CGI Tool) is created. The view sur- 
face descriptor returned in name refers to the CGI Tool. The ptr element specifies the size and 
placement of the CGI Tool. Ptr is a pointer to a nine element array of characters. Each element 
of the array should be filled with an integer. The first two elements specify the x- and y- 
coordinates of the upper left-hand corner of the CGI Tool. The third and fourth elements specify 
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the width and height of the CGI Tool The fifth through eighth elements specify the position and 
size of the iconic form of the CGI Tool If the ninth element is nonzero, the tool is displayed in 
its iconic form. 


ERRORS: 

5 ENOTOPOP 

11 ENOWSTYP 

12 EVSISOPN 


CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 

Specified view surface type does not exist. 

Specified view surface is open. 


Table 2-2: Available View Surfaces 


Surface Name 

Description 

BW1DD 

for the Sun-1 monochrome display 

BW2DD 

for the Sun-2 monochrome display 

CG1DD 

for the Sun-1 color display 

CG2DD 

for the Sun-2 color display 

PIXWINDD 

for windows on the Sun-1 monochrome display 

CGPIXWINDD 

for windows on color display 


Table 2-3: View Surface Default States 


State 

Value 

View Surface 

(Cleared) 

Device Viewport 

(Total Screen) 


2.1.8. activate_vws (Cactvwsj 

Cerror activate_vws (name) 

Cint name; /* view surface name */ 

activate_vws activates the view surface specified by name. Future SunCGI calls affect this 
view surface. Nothing ts displayed on a vtew surface unless that view surface is active. Note 
that activating a view surface may reset the state of SunCGI. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 

10 EVSIDINV Specified view surface name is invalid. 
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13 EVSNOTOP Specified view surface not open. 

14 EVSISACT Specified view surface is active. 

2 .I. 4 . deactivate_vws (Cdeactvws) 

Cerror deact ivate_vws (name) 

Cint name; /* view surface name */ 

deactivate_vws prevents calls to SunCGI functions from having an effect on this view sur- 
face. The view surface may be reactivated at a later time without having to be reopened. Note 
that activating a view surface may reset the state of SunCGI. 

ERRORS: 


4 

ENOTVSAC 

CGI not in proper state: CGI shall be in state VSAC. 

10 

EVSIDINV 

Specified view surface name is invalid. 

13 

EVSNOTOP 

Specified view surface not open. 

15 

EVSNTACT 

Specified view surface is not active. 


2.1.5. close_vws fCclosevwsj 

Cerror close_vws (name) 

Cint name; /* view surface name */ 

close_vws terminates a view surface. Future SunCGI calls have no effect on this view sur- 
face. The view surface cannot be reactivated without being reopened. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VS AC. 

10 EVSIDINV Specified view surface name is invalid. 

13 EVSNOTOP Specified view surface not open. 


2.1.6. close_cgi (Cclosecgi^ 

Cerror close_cgi() 

close_cgi terminates all open view surfaces, and restores the state of the window system to 
the state that it was in before SunCGI was opened. Future SunCGI calls will have no effect 
and will generate errors. 
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It is recommended that you include a call to close_cgi in the exit routines of your applica- 
tion program to guarantee leaving the window system and SimCGI in a stable state. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VS AC. 


2.2. Interface Negotiation 

CGI is intended to support a ‘negotiated device interface’ which permits programs written on a 
specific type of hardware to run on other machines. SunCGI only allows inquiry of most of the 
settable modes. 4 For example the user may want to find out which types of input devices are 
supported. However, functions for setting color precision, coordinate type, specification mode, 
and color specification are not provided because SunCGI only supports one type of color preci- 
sion (8-bit), coordinate type (integers), and color specification (indexed). The width and size 
specification modes are settable, but the functions which set them are described in the chapter 
on attributes. However, the inquiry negotiation functions are supported so that an application 
program written for a CGI on another manufacturers’ workstation can find out whether the 
SunCGI is capable of running that application. 


2.2.1. inquire_device_identification (Cqdevidj 


Cerror inquire_device_idervtif ication (name,devid) 

Cint name; /* device name */ 

Cchar *devid; /* Workstation type */ 

inquire_device_identif ication reports which type of Sun Workstation view surface 
name is associated with. The argument devid may be set to one of the six Sun Workstation 
types: BWlDD, BW2DD, CG1DD, CG2DD , PIXWINDD , or CGPIXWINDD . The inclusion of 
the name argument deviates from the ANSI standard, but is necessary so that the characteristics 
of individual view surfaces may be inquired. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 

10 EVSIDINV Specified view surface name is invalid. 

13 EVSNOTOP Specified view surface not open. 


* The functions which are not supported by SunCGI are classified as non-required by the March 1084 
ANSI OGa standard. 
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2 . 2. 2. inquir e_dev ice_c lass fCqdevc 1 assj 


Cerror inquire_device_class (output , input) 

Cint * output , * input; /* output and input abilities */ 

inquire_device_class describes the capabilities of Sun Workstations in terms of the CGI 
functions they support 5 . Each of the two returned values reports the number of functions of 
each of the two classes which are supported in SunCGI. These numbers (the values of input and 
output) are used to make more detailed inquiries by using functions such as 
inquire_output_capabi 1 it ies. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 


2.2.3 . inquire_physical_coordinate_system (Cqphyscsys) 


Cerror inquire_physical_coordinate_system 

(name , xbase , ybase , xext # yext , xunits , yunits) 

Cint name; /* name assigned to cgi view surface */ 

Cint *xbase, *ybase; /* base coordinates */ 

Cint *xext , *yext ; /* number of pixels in each direction */ 
Cfloat *xunits, *yunits; /* number of pixels per mm. */ 


inquire_coordinate_system reports the physical dimensions of the coordinate system of 
view surface name in pixels and millimeters. The inquire_coordinate_system function is 
provided to permit the drawing of objects of a known physical size. 
inquire_coordinate_system is also provided to assist in the computation of parameters for 
the device_viewport function. Xext and yext describe the maximum extent of the window 
in which the application program is run (The window may or may not cover the entire screen.) 
The number of pixels per millimeter is always set to 0 because the actual screen size of device 
varies between individual monitors. If you want to compute the actual size of the screen, you 
may obtain the number of pixels in the x and y directions from the monitor specifications and 
perform the division in your application program. 


ERRORS: 


5 

ENOTOPOP 

CGI not 
VSAC. 

10 

EVSIDINV 

Specified 

13 

EVSNOTOP 

Specified 


in proper state CGI shall be 

view surface name is invalid, 
view surface not open. 


either in state CGOP, VSOP, or 


6 The output argument does not include the non-standard CGI functions. 
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2.2.4. inquire_output_function_set fCqoutf unset/ 

Cerror inqulre_output_function_set (level, support) 

Cint level; /* level of output */ 

Csuptype ‘support /* amount of support */ 

inquire_output_function_set reports the extent to which each level of the output por- 
tion of the ANSI CGI standard is supported. 

typedef enum •( 

NONE, 

REQUIRED_FUNCTIONS_ONLY, 

SOME_NON_REQU I RE D_F UNCTIONS , 

ALL_NON_REQUIRED_FUNCTIONS 
y Vsuptype; 

The standard requires that the level argument be an enumerated type; however, for reasons of 
simplicity only the level number is used by SunCGI. Levels 1-6 are supported completely (that 
is, both required and non-required functions are implemented. Level 7 is not supported at all. 
Refer to the ANSI standard for the precise definition of each level. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VS AC. 


2.2.5. inquire_vdc_type (Cqvdctypej 

Cerror inquire_vdc_type (type) 

Cvdctype ‘type; /* type of vdc space */ 

inquire_vdc_type reports the type of coordinates used by SunCGI in the returned argu- 
ment type. 

typedef enum *( 

INTEGER, 

REAL, 

BOTH 

} Cvdctype; 

Type is always set to INTEGER (32-bit). Use SunCore if you want to use a system with coordi- 
nate space expressed in real numbers. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 


Revision A of 15 May 1985 


2-9 



Initializing (and Terminating) SunCGI 


SunCGI Reference Manual 


2. 2. 6. inquir e_output_capabi 1 i t ies fCqoutcap ) 

Cerror inquir©_output_capabilities ( first , num, list) 

Cint first, num; /* first and number elements 

of list to be returned */ 

Cchar *list[]; /* returned list */ 

inquire_output_capabiliti.es lists the output functions in the returned argument list. 
The range of the first and num arguments is determined by the returned argument output from 
the inquire_device_class function. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 

16 EINQLTL Inquiry arguments are longer than list. 


2 . 2. 7. Input Capability Inquiries 

Input devices have a separate class of negotiation functions. Input capability inquiries report 
qualitative abilities as well as quantitative abilities of input devices. The 
inquire_input_capabilities function reports which devices and overall features are sup- 
ported by SunCGI. The remaining functions report the capabilities of individual devices or 
fe atures. 


Input devices are virtual devices which must be associated with physical triggers (such as 
mouse buttons). Initializing an input device defines the measure used by a device, for example 
initializing a LOCATOR device defines the measure as x,y coordinates. In addition to being 
associated with a trigger, each device has selectable screen echoing capabilities. Association and 
echoing capabilities for each input device are reported by the functions described in this section. 


2. 2.7.1. inquire_input_capabilities /Cqinpcaps^ 


Cerror inquire_input_capabiliti.es (valid, table) 

Clogical *valid; /* device state */ 

Ccgidesctab *table; /* CGI input description table */ 

inquire_input_capabilities reports the total number of input devices of each class that 
are supported. The argument valid returns the value L_TRUE if SunCGI is initialized, and 
LJFALSE otherwise. If valid is set to L_TRUE, the elements of table are set to the quantity and 
quality of inputs supported by the specific view surface. All Sun Workstations support input 
at the same level. 
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typed© f struct { 

Cint numloc; 

Cint numval; 

Cint numstrk; 

Cint numchoice; 

Cint numstr; 

Cint numtrig; 

Csuptype event_queue; 

Csuptype asynch; 

Csuptype coord_map; 

Csuptype echo; 

Csuptype tracking; 

Csuptype prompt; 

Csuptype acknowledgement; 

Csuptype trigger_manipulation; 

} Ccgidesctab; 

Elements of type Cint report how many of each type device is supported, as well as how many 
types of triggers are supported. Elements of type Csuptype report how many of the functions of 
each class are supported. All functions except the tracking functions are fully supported. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 


2.2.7. 2. inquire_lid_capabilities (Cqlidcaps^ 


Cerror inquire_lid_capabilities (devclass, devnum, valid, table) 

Cdevoff devclass; 

Cint devnum; /* device type, device number */ 

Clogical *valid; /* device supported at all */ 

Cliddescript *table; /* table of descriptors */ 

±nquire_input_device_capabilities describes the capabilities of a specific input device 
(hereafter, specified device). The input arguments devclass and devnum refer to a specific dev- 
ice type and number. The argument valid reports whether CGI is initialized. 

typed© f struct { 

Clogical sample; 

Cchangetype change; 

Cint numassoc; 

Cint *trigassoc; 

Clogical prompt; 

Clogical acknowledgement ; 

Cechoav *echo; 

Cchar *classdep; 

Cstatelist state; 

} Cliddescript; 
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The elements of table which are of type Clogical indicate whether an ability is present in a 
specified logical input device. The change element reports whether associations are changeable 
at all (all input devices except string are not changeable). The numassoc and trigaesoc elements 
of table report how many and which triggers are associated with the specified logical input dev- 
ice. The echo argument describes which echo types are supported (see the chapter on input for 
a list of echo types 6 ). The clasadep argument provides class dependent information in character 
form (the type of information is given in Table 2-3). If more than one piece of class dependent 
information is returned, then the pieces of information are separated by commas. The ttate 
argument reports the initial state of the specified device. See the inquire_state_list func- 
tion. 


Table 2-4: Class Dependent Information 


Device Class 

Information 

Possible Values 

IC_LOCATOR 

Coordinate Mapping 

(Yes, No, Partial) 


Native Range 

(xmin,xmax,ymin,ymax) 

IC_VALUATOR 

Set Valuator Range 

(yes/no) 

IC_STROKE 

Time Increment Settable 

(yes/no) 


Minimum Distance 

(yes/no) 

IC.CHOICE 

Range 

(min/max) 

IC_STRING 

None 

None 


ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VS AC. 


2 . 2 . 7 . 3 . inquire_trigger_capabilities (fcqtrigcaps^ 


Cerror inquire_trigger_capabilities (trigger , valid, tdis) 

Cint trigger; /* trigger number */ 

Clogical ‘valid; /* trigger supported at all */ 

Ctrigdis *tdis; /* trigger description table */ 

inquire_trigger_capabilities describes how a particular trigger can be associated. The 
argument valid reports whether the device supports input at all. 


3 Note that lnqulra_l id_capabi 1 It ies returns an enumerated type whereas track_on accepts 
integers. Therefore these values may be different. 
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typed© f struct { 

Cchangetyp© change; 

Cassoclid *numassoc; 

Cint maxassoc; 

Cpromstat© prompt; 

Cackstat© acknowledgement; 

Cchar *name; 

Cchar * descr ipt ion ; 

} Ctrigdis; 

The change element of tdis reports whether the specified trigger can be associated with a logical 
input device. The numassoc and trigassoc elements of tdis report how many and which logical 
input devices can be associated with trigger. The maxassoc element reports the maximum 
number of devices that can be associated with a particular trigger. The prompt and ack- 
nowledgement elements report the ability of the trigger to support these abilities. SirnCGI does 
not support either prompt or acknowledgement for any input device. The name element is sim- 
ply a character form of the trigger name (for example, LEFT MOUSE BUTTON). The description 
element is never filled and is included for standards compatibility. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 

86 EINTRNEX Trigger does not exist. 

2*3. View Surface Control 

The functions described in this section 

1. define the range of world and device coordinates, 

2. control clipping, and 

3. reset selected aspects of the view surface and the internal state of SunCGI. 

2.3.1 . Coordinate Definition 

Most functions in SunCGI express coordinates in VDC Space (Virtual Device Coordinate Space). 
In conventional computer graphics terms, VDC Space corresponds to world coordinate space. 
The mapping between VDC Space and screen space is determined by the physical size of the 
screen in pixels. Screen space is set by default to the entire size of the screen or the graphics 
window depending on the device type. The mapping from VDC Space to screen space is always 
isotropic (the shape of the rectangle defining screen space is the same shape as VDC Space). 
Therefore, VDC Space defines the shape of the active view surface. The portion of screen space 
which does not correspond to VDC Space is ignored. The aspect ratio (the ratio between the 
height and width) is therefore, defined by VDC Space and not screen space. 
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2.3. 1.1. vdc_extent f Cvdcext ) 


Cerror vdc_extent (cl, c2) 

Ccoor *cl, 4 c2; /* bottom left-hand and top right-hand 

corner of VDC space 4 / 

vdc_extent defines the limits of VDC Space. The range of the coordinates must be between 
—32767 and 32767 (or an error is generated). VDC Space can be set by you, but it ranges from 0 
to 32767 in both the X and the Y directions by default. Resetting VDC Space impacts the display 
of output primitives on all view surfaces. 


Resetting the limits of VDC Space automatically redefines the clipping rectangle to the new 
limits of VDC Space, regardless of the value of the clip indicator. 

Changing the mapping from screen space to VDC Space allows you to translate (move) or scale 
(zoom in/zoom out) the output primitives. However, no rotation functions are provided by 
SunCGI, and therefore, must be built by you. The code fragment below translates and zooms 
in on a rectangle: 
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#includ© <cgidefs.h> 
main () 

{ 

Cvwsur f device; 

Cint name; 

Ccoor upper, lower; 

Cint xl,yl,xu,yu; 

Ccoor dvl,dv2; 

device. dd = PIXWINDD; /* turn on a pixwin */ 
open_cgi () ; 

open_vws (&name, &device) ; 

act i vat e_view_sur face (name) ; 

lower. x=30; /* coordinates of rectangle */ 

lower .y=30; 

upper . x=70 ; 

upper . y=70 ; 

dvl.x = 0; 

dvl .y = 0; 

dv2.x = 200; 

dv2.y = 200; 

vdc_extent (&dvl,&dv2) ; 

rectangle (Supper, Slower) ; /* draw initial rectangle */ 

sleep (4) ; 

dvl.x = 0; 

dvl.y = 0; 

dv2.x = 100; 

dv2.y = 100; 

vdc_extent (&dvl,&dv2) ; /* center rectangle */ 

rectangle (Supper, Slower) ; 

sleep (4) ; 

dvl.x = 20; 

dvl.y = 20; 

dv2.x = 80; 

dv2.y = 80; 

vdc_extent (Sdvl , Sdv2) ; /* enlarge rectangle */ 

rectangle (Supper, Slower) ; 
sleep (4) ; 

close_view_sur face (name) ; 
close_cgi () ; 

> 


ERRORS: 

5 ENOTOPOP 

20 EBADRCTD 
24 EVDCSDIL 


CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VS AC. 

Rectangle definition is invalid. 

VDC space definition is illegal. 
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2. 3. 1.2. device_viewport (Cdevvpt) 


Cerror devic©_vi©wport (name, cl, c2) 

Cint name; /* naxn© assigned to cgi view surface */ 

Ccoor *cl,*c2; /* bottom left-hand and top right-hand corner of view 

surface to map device onto (expressed in pixels) */ 


device__viewport redefines the limits of screen space. If the new limits are not less than or 
equal to the size of the current screen or window size, an error is returned. Although 
device_viewport does not redefine the aspect ratio, it may redefine which areas of the screen 
are unused. 

ERRORS: 


5 

ENOTOPOP 

CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 

10 

EVSIDINV 

Specified view surface name is invalid. 

13 

EVSNOTOP 

Specified view surface not open. 

20 

EBADRCTD 

Rectangle definition is invalid. 

21 

EBDVIEWP 

Viewport is not within Device Coordinates. 


2.3. 2. Clipping 

For some application programs, it is desirable to have clipping explicitly within the viewport, 
while other applications may seek to increase efficiency by not checking if the coordinates are 
within the bounds of the clipping area. 

All SunCGI application programs will run faster if clipping is turned off. However, clipping is 
turned on by default to prevent SunCGI from drawing outside of the bounds of the window. 

The clipping area is set by the clip_rectangle function. 


2. 3. 2.1. clip_indicat:or ^Cclipind/ 


Cerror clip_indicator (cf lag) 

Cclip cf lag; /* CLIP_RECTANGLE , VDCJEXTENT, or OFF */ 

The value of the argument cflag determines whether output primitives are clipped before they 
are displayed. The default state is vdc_extent. The advantage of turning clipping off is that it 
improves the speed of drawing primitives. However, if clipping is turned OFF, SunCGI may 
draw output primitives outside of the window or within the bounds of an overlapping window. If 
clipping is not OFF, output primitives are clipped to either the clip rectangle, (if cflag equals 
CLIP) or the full extent of VDC space or (if cflag equals CLIP). 
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typed© f enum { 
CLIP, 

NOCLIP, 

CLIP_RECTANGLE 
> Vclip; 


ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 


2. 3. 2. 2. clip_rectangle (CclLprect) 


Cerror cl ip_rect angle (xmin, xmax,ymin,ymax) 

Cint xmin , xmax , ymin , ymax ; /* bottom left-hand 

and top right-hand corner of clipping rectangle */ 

clip_rect:angle defines the clipping rectangle in VDC Coordinates. By default, the clipping 
rectangle is set to the borders of VDC space. The clipping rectangle impacts all view surfaces. 

ERRORS: 


5 

ENOTOPOP 

CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 

20 

EBADRCTD 

Rectangle definition is invalid. 

22 

ECLIPTOL 

Clipping rectangle is too large. 

23 

ECLIPTOS 

Clipping rectangle is too small. 


2.3.3 . Device Control 

Device control functions restore the view surface and the internal state of SunCGI to a known 
state. The individual aspects of the device which can be reset are the output attributes, the 
view surface (screen), and the error reporting. 


2. 3. 3.1. hard_reset (Chardrst.) 

Cerror hard_reset() 

hard_reset returns the output attributes to their default values; terminates all input devices, 
and empties the event queue and clears all view surfaces. VDC Space is reset to its default 
values and the clip indicator is set to CLIP. 
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This function should be used sparingly because most control, attribute, and input functions 
called before this function will not have any effect on functions called after hard_reset is 
called. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VS AC. 


2.8. 3. 2. reset_to_de faults (Crsttodefs^ 

Cerror reset_to_d® faults () 

reset_to_de faults returns output attributes to defaults. reset_to_de faults does not 
clear the screen, reset the input devices, or reset the character set index. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 

10 EVSIDINV Specified view surface name is invalid. 

2. 3. 8. 3. clear_view_sur face (Cclrws) 


Cerror clear_view_sur face (name, def flag, Index) 

Cint name; /* name assigned to cgi view surface */ 

Cflag defflag; /* default color flag */ 

Cint index; /* color of cleared screen */ 

clear_view_sur face changes all pixels in the relevant area of the view surface specified by 
name to the color specified by the index argument, unless the defflag argument is set to OFF. If 
defflag is equal to OFF, the view surface is cleared to color zero. The area of the view surface 
which is actually cleared is determined by the clear_control function. 
clear_view_sur face also resets the internal state of SunCGI according to previous calls to 
the clear_control function. clear_view_sur face resets the current background color 
to the color of the cleared view surface. 

ERRORS: 


4 

ENOTVSAC 

CGI not in proper state: CGI shall be in state VSAC. 

10 

EVSIDINV 

Specified view surface name is invalid. 

13 

EVSNOTOP 

Specified view surface not open. 

15 

EVSNTACT 

Specified view surface is not active. 

35 

ECINDXLZ 

Color index is less than zero. 

36 

EBADCOLX 

Color index is invalid. 
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2. 8.3.4. clear_control /Cclrcont^ 


Cerror clear_control (soft .hard, intern .extent) 

Cacttype soft, hard; /* so ft -copy action, hard-copy action */ 
Cacttype intern; /* internal action */ 

Cexttyp© extent; /* clear extent */ 


clear_control determines the action taken when clear_view_sur face is called. The 
argument soft can be set to either NO_OP or CLEAR. The argument hard which regulates clearing 
rules for plotters is ignored (because SunCGI does not currently support hard-copy devices) and 
is included only for ANSI CGI compatibility. The argument intern is set to either RETAIN or 
CLEAR. This parameter was included to support segmentation storage which is not currently a 
part of ANSI CGI. Therefore, the intern argument is ignored. The argument clear_extent is 
set to either VIEWJSURFACE, VIEWPORT, or CLIPJtECTANGLE and determines what area of the 
screen is cleared. The default states are CLEAR ( soft ), NO_OP ( hard ), RETAIN (infern), and 
VTEW_SURFACE (extent). 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 


2 . 3 . 3 . 5 . set_error_warning_mask fCserrwarnmky 


Cerror set_error_warning_mask (action) 

Cerrtype action; /* Action on receipt of an error */ 

set_error_warning_mask 7 determines the action taken by SunCGI when an error occurs. 
Three types of action are possible: NO^ACTION, POLL, INTERRUPT. If the action argument is set 
to NO.ACTION, errors are detected internally, but not reported. 


The user is advised not to set the action argument to NO_ACTION. 

If the action argument is set to POLL, errors are detected and the returned value of the function 
is set to the error number. Error handling is therefore, left up to the application programmer. 
If the action is set to INTERRUPT an error message is printed on the terminal, and the program is 
stopped if the error is FATAL (See Appendix D). The default error_varning_mask is INTER- 
RUPT. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 


7 The syntax of 6et_error_warning_mask in SunCGI is slightly different from the proposed ANSI 
standard in that the ANSI definition allows different actions for different classes of errors. 
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2.4. Running SunCGI in the Window System 

Two aspects of SunCGI pertaining to the window system are: 

1. varying the size of graphics windows, and 

2. handling SIGWINCHes (interrupt signals generated by changes to the view surface made by 
the window system). 

Changing the Window Size 

When the window size changes during execution time, the scale factors which map VDC Space 
into screen space are modified. More importantly, unless the application program has explicitly 
opened a view surface as a retained view surface, overlapping other windows destroys the picture 
in the graphics subwindow below, In this case, the picture must be regenerated by re-running the 
application program. 

2.4.2. Passing SIGWINCHes to the Application Program 

When a view surface is initialized or changed, the SIGWINCH signal is normally trapped by 
SunCGI. However, the SIGWINCH signal is passed up to the application program if the applica- 
tion program provides a SIGWINCH handling routine by using the set_up_sigvinch function. 
Under no circumstances will the user be able to access the SIGWINCHes generated when the view 
surface is initialized. Therefore, the set_up_sigvinch routine is primarily intended for users 
who want to activate a display list for picture regeneration, for example, when the size of the 
view surface has changed. If the view surface is retained, the pictures is redisplayed if the size 
of the view surface has not changed. 

2.4-3. set_up__sigwinch fCsupsigj 

Cerror set_up_sigwinch (name, sig_function) 

Cint name; 

Cint *sig_function () ; /* signal handling function */ 

set_up_sigwinch is a nonstandard SunCGI function that allows the application program to 
trap SIGWINCHes for viewsurface name. If the sig_ function argument is nonzero, all 
SIGWINCHes which are not trapped by the internals of SunCGI (that is, view surface initializa- 
tion, and changing the size of the window) are passed to the function specified by 
sig_ function. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be either in state CGOP, VSOP, or 
VSAC. 
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Output 


SunCGI supports two classes of output primitives: geometrical output primitives and raster 
primitives. 

Geometrical Output Primitives 

include arcs, circles, polylines, and polygons. The position of geometrical output primitives 
are always specified in absolute VDC coordinates®. 

Raster Primitives 

draw text and scaled and unsealed two-dimensional arrays. The coordinate system for ras- 
ter primitives depends on the type of primitive: cell array, pixel array, or bitblt (bit block 
transfer). The drawing mode determines how output primitives are drawn on top of other 
output primitives or the background. 


3.1. Geometrical Output Primitives 

Geometrical output primitives are divided into two classes: polygonal primitives and conical 
primitives. Geometrical output primitives are all two-dimensional in keeping with the CGI stan- 
dard. However, polygons with holes (via the partial_polygon function) are provided in 
order to support three-dimensional graphics packages. 


3.1.1. Polygonal Primitives 

Most polygonal primitives (polyline, polymarker, polygon, and partial_polygon) 
take one argument of type Ccoorlist: 


8 SunCGI (unlike SunCore) maintains no concept of current position. 
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typed© f struct { 

Cint x; 

Cint y; 

} Ccoor; 

typed© f struct { 

Ccoor *ptlist; 

Cint n; 

} Ccoor list; 

The element ptlist is really a pointer to an array of type Ccoor which contains the coordinates 
of the points defining the primitive. The style, color, and other features of lines, markers, and 
fill patterns used by geometrical output primitives are set by the attribute functions described in 
the next chapter. 

The polygons generated by SunCGI may or may not be closed. SunCGI automatically assumes 
the polygon is closed for the purpose of filling. However, a polygon must be explicitly closed in 
order to get all of its edges drawn, so take care to generate explicitly closed polygons. However, 
the rectangle function implicitly generates closed objects 9 . 

3. 1.1.1. polyline /Cpolyline^ 

Cerror polyline (polycoors) 

Ccoorlist *polycoors; /* list of points */ 

polyline draws lines between the points specified by the ptlist element of polycoors. polyline does 
not draw a line between the first and last element of the point list. To generate a closed poly- 
line, the last point on the list must have the same coordinates as the first point on the list. The 
style, color, and width of the lines are set by the polyline_bundle_index, line_type, 
line_color, line_vidth, and line_width_specif ication_mode functions. If a line 
segment of a polyline has a length of zero, the line is not drawn. To draw a point use the circle 
function. If you specify a polyline that has less than two points an error is generated. Similarly, 
if the number of points specified is greater than the maximum number of points (255), an error is 
generated. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

60 ENMPTSTL Number of points is too large. 

61 EPLMTWPT polylines must have at least two points. 

S. 1.1. 2. dis joint _poly line ^Cdpolyline,/ 


9 The only instance in which rectangle does not produce a closed object is if one of the corners exceeds a 
clipping boundary. 
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Cerror dis joint_polyline (polycoors) 

Ccoorlist ‘polycoors; /* list of points */ 

disjoint_polylina draws lines between pairs of elements in ptlist. The style, color, and 
width of the lines are set by the polyline_bundle_index, line_type, line_color, 
line_vidth, and line_vidth_specification_mode functions. If polycoors contains an 
odd number of points, the last point is ignored. As with polyline, if the number of points is 
less than two or greater than 256, an error is generated. disjoint_polyline is typically 
used to implement scan-line polygon filling algorithms. 

ERRORS; 

4 ENOTVSAC CGI not in proper state; CGI shall be in state VSAC. 

60 ENMPTSTL Number of points is too large. 

61 EPLMTWPT polylines must have at least two points. 


3. 1.1.3. polymarker ^polymarker,/ 


Cerror polymarker (polycoors) 

Ccoorlist ‘polycoors; /* list of points */ 

polymarker draws a marker at each point. The type, color, and size of marker are set by the 
polymarker_bundle_index, marker_type, markar_color, marker_size, and 
marker_size_speci f ication_mode functions. If the number of points specified is greater 
than the maximum number of points, an error is generated, polymarker is useful for making 
graphs such as scatter plots. 

ERRORS: 

4 ENOTVSAC CGI not in proper state; CGI shall be in state VSAC. 

60 ENMPTSTL Number of points is too large. 

3. 1.1.4. polygon /Cpolygon/ 


Cerror polygon (polycoors) 

Ccoorlist ‘polycoors; /* list of points */ 

polygon displays the polygon described by the points in polycoors. In addition, any points added 
to the global polygon list by the partial_polygon function are also displayed. The polygon is 
filled between edges. Polygons are allowed to be self-intersecting. The visibility of individual 
edges can only be set by the partial_polygon function. The pattern and color used to fill 
the polygon are set by the functions described in the solid attributes section of the attributes 
chapter. The characteristics of the edges are controlled by the perimeter attribute functions and 
not the line attribute functions (which regulate the drawing of polylines ). The number of points 
in the polygon used to determine the error condition of too few points is the total number of 
points on the global polygon list not the number of points specified in polycoors. 

ERRORS: 
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4 ENOTVSAC 
60 ENMPTSTL 

62 EPLMTHPT 

63 EGPLISFL 


CGI not in proper state: CGI shall be in state VSAC. 
Number of points is too large. 

Polygons must have at least three points. 

Global polygon list is full. 


3. 1.1.5. partial_polygon /Cppolygon^ 


Cerror partial_polygon (polycoors, flag) 

Ccoorlist ‘polycoors; /* list of points */ 

Ccflag flag; /* add to point buffer */ 

partial_polygon adds elements to the global polygon list without displaying the polygon. 
The flag controls whether the previous polygon on the global polygon list is open or closed. If the 
cflag is set to CLOSED, the last polygon on the global polygon list is closed by drawing a visible 
perimeter edge between the last and the first points of the last polygon in the global polygon list. 
If the cflag is set to OPEN, an invisible perimeter edge is drawn between the last and the first 
points of the last polygon in the global polygon list. The partial_polygon function provides 
the capability of drawing multiple-boundary polygons, including polygons with holes. 
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#include ”cgidefs.h" 

{ 


Ccoor list [4] ; 
Ccoorlist points; 


inter ior_style(SOLIDI, ON) ; 

list [0] .x = 10000; 

list [0] .y = 10000; 

list [1] .x = 10000; 

list [1] .y = 20000; 

list [2] .x = 20000; 

list [2] .y = 20000; 

list [3] .x = 20000; 

list [3] .y = 10000; 

points .ptlist=list ; 

points .n=4; 

part ial_polygon (^points, CLOSE) ; /* draw large solid square */ 

list [0] .x = 12500; 

list [0] .y = 12500; 

list [1] .x = 12500; 

list [1] .y = 17500; 

list [2] .x = 17500; 

list [2] .y = 17500; 

list [3] .x = 17500; 

list [3] .y = 12500; 

points .ptlist=list ; 

points .n=4; 

polygon (^points) ; /* cut a hole in it */ 

> 


An error is detected if the number of points on the global polygon list exceeds 255. In this case, 
the polygon on the global polygon list is drawn, and the new information is not added. The same 
error handling applies to polygon. 


ERRORS: 

4 ENOTVSAC 
60 ENMPTSTL 

62 EPLMTHPT 

63 EGPLISFL 


CGI not in proper state: CGI shall be in state VSAC. 
Number of points is too large. 

Polygons must have at least three points. 

Global polygon list is full. 


8. 1.1.6. rectangle /Crectangle^ 
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Cerror rectangle (rbc, ltc) 

Ccoor *rbc, 4 ltc; /* corners defining rectangle */ 

rectangle displays a box with its lower right-hand corner at point rbc and its upper left-hand 
corner at point ltc. The fill pattern is determined by the solid object attribute functions. Calls 
to rectangle do not affect the global polygon list. The interior of the rectangle (the filled portion) 
is defined by Ire and ulc. The perimeter is drawn outside of this region. The appearance of the 
rectangle is determined by the fill area and perimeter attributes. 

If the arguments to rectangle would result in a point or a line, the point or line is drawn. How- 
ever, if the arguments to rectangle determine a point, the point is drawn with width zero, 
regardless of the current value of perimeter_width. If the values of Ire and ulc are reversed, the 
points are automatically reversed and the rectangle is drawn normally. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

3.1.2. Conical Primitives 

SunCGI has two classes of conical primitives: circular and elliptical. Each class has functions 
for drawing solid objects, arcs, and closed arcs. Drawing of conical primitives is regulated by the 
same attributes that regulate the drawing of polygons and polylines. 


3 . 1 . 2 . 1 . circle (Ccircle) 

Cerror circle (cl, rad) 

Ccoor *cl; /* center */ 

Cint rad; /* radius */ 

circle draws a circle of radius rad centered at cl. The argument rad is expressed in terms of 
VDC Space. The color, form, and visibility of the interior and perimeter are controlled by the 
same solid object attributes which control the drawing of polygons and rectangles. 

The argument rad determines the size of the inside of the circle. Therefore, a circle with a thick 
perimeter may be larger than expected. If the radius is zero, a point is drawn, and no textured 
perimeter is drawn, even if the perimeter width is large. If the radius is negative, the absolute 
value of the radius is used. 

Textured circles may possibly contain an incorrect element at one point because the digital cir- 
cumference may not be exactly divisible by the length of the texture element. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

3 . 1 . 2 . 2 . circular_arc_center (Ccircarccent) 
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Cerror circular_arc_c@nter (cl , c2x„ c2y , c3x„ c3y„ rad) 

Ccoor *cl; /* center */ 

Cint c2x, c2y, c3x, c3y; / & endpoints */ 

Cint rad; /* radius */ 

circular_arc_center draws a circular arc through points c2x , c2y and cSz, cSy with circle 
of radius rad at center cl. Point c2x, c2y is the starting point and point cSx, c3y is the ending 
point. If c2x, c2y or cSx , cSy are not on the circumference of the circle, an error is generated 
and the arc is not drawn. Circular arcs are drawn in a counterclockwise manner. This conven- 
tion is used to determine the difference between the arc formed by the obtuse angle determined 
by cl.x, cl.y, c2x , c2y , and cSx , cSy and the acute angle specified by these same points. There- 
fore switching the values of c2x, c2y and c3x y cSy will produce complementary arcs. 


If rad is negative, the points 180 degrees opposite from c2x, c2y . and cSx, c3y are used as the 
endpoints of the arc. 

If the rad is zero, a point is drawn at cl. If either c2x, c2y or cSx, cSy are not on the perimeter 
of the circle determined by cl and rad , an error is generated and the arc is not drawn. The 
attributes which determine the style, width, and color of the arc are the same functions which 
regulate the drawing of polylines. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

64 EARCPNCI Arc points do not lie on circle. 

3. 1.2. 3. circular_arc_center_close (CcLrcarccentcl) 


Cerror circular_arc_center_close (cl, c2x, c2y, c3x, c3y, rad, close) 
Ccoor *cl; /* center */ 

Cint c2x, c2y, c3x, c3y; /* endpoints */ 

Cint rad; /* radius */ 

Cclosetype close; /* PIE or CHORD */ 

circular_arc_center_clos@ draws a closed arc centered at cl with radius rad and end- 
points c2x, c2y and cSz, cSy. Arcs are closed with either the PIE or CHORD algorithm. The PIE 
algorithm draws a line from each of the endpoints of the arc to the center point of the circle. 
SunCGI then fills this region as it would any other solid object (that is, it uses the fill area attri- 
butes ). The CHORD algorithm draws a line between the endpoints of the arc and then fills this 
region. circular_arc_center_close is useful for drawing pie charts (see following exam- 
pie): 
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#includ© <cgid©fs.h> 


{ /* draws four quadrants in different colors */ 

Cint radius; 

Ccoor cl; 

interior_styl©(SOLIDI,OFE) /* s©t arc type to SOLID and no visible perimeter */ 
cl.x = 16000; /* center */ 
cl.y = 16000; 

radius =8000; /* radius */ 

fill_color (1) ; /* color of quadrant 1 */ 

circular_arc_center_close (&cl, 16000 / 24000, 24000, 16000, radius, PIE) ; 
fill_color (2) ; /* color of quadrant 2 */ 

circul ar__arc_cent©r_clos© (&cl, 16000, 24000, 12000, 16000, radius, PIE) ; 
f ill__color (3) ; /* color of quadrant 3 */ 

c ir cu 1 ar_ar c_cent er _c lose (&cl , 12000, 16000, 12000, 16000, radius , PIE) ; 
fill_color (4) ; /* color of' quadrant 4 */ 

circular_arc_center_clos© (&cl, 12000, 16000, 24000, 16000, radius, PIE) ; 
sleep (10); 

> 


ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

64 EARCPNCI Arc points do not lie on circle. 

3. 1.8. 4- circular_arc_3pt (CcLrcarcthree) 

Cerror circular_arc_3pt (cl , c2, c3) 

Ccoor *cl,*c2,*c3; /* starting, intermediate, and ending points */ 
Cint rad; /* radius */ 

circular_arc_3pt draws a circular arc starting at point cl and ending at point c3 which is 
guaranteed to pass through point c2. If the circular arc is textured (for example, dotted) then 
the intermediate point may not be displayed. However, if the arc is solid, the intermediate point 
is always drawn. If the three points are colinear, a line is drawn. If two of the three points are 
coincident, a line is drawn between the two distinct points. Finally, if all three points are coin- 
cident, a point is drawn. circul ar_arc_3pt is considerably slower than 
circular_arc_center, therefore, you are advised to circul ar_arc_cervter if both func- 
tions can meet your needs. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 
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8. 1.2. 5. circular_arc_3pt:__clos© fCcircarcthreeclj 


Cerror circular_arc_3pt_clos© (cl , c2, c3, clos©) 

Ccoor *01, *c2, *c3; /* starting, intermediate, and ending points */ 
Cclosetyp© close; /* PIE or CHORD */ 

circular_arc_3pt_clos© draws a circular arc starting at point cl and ending at point c8 
which is guaranteed to pass through point c2. As with circular_arc_3pt, 
circular_arc_3pt_close is considerably slower than circular_arc_center__close; 
therefore, you are advised to use circular_arc_ cent@r_close if both functions meet your 
needs. 

If the three points are colinear, a line is drawn. If two of the three points are coincident, a line 
is drawn between the two distinct points. Finally, if all three points are coincident, a point is 
drawn. In none of these cases will any region be filled. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

3. 1.2. 6. ©Hips© ^Cellipse^ 


Cerror ellipse (cl, majx,miny) 

Ccoor *cl; /* center 

Cint majx,miny; /* enpoints of x and x axes */ 

ellipse draws an ellipse centered at point cl with major(x) and minor (y) axes which terminate at 
majx and miny 10 . If either majz or miny are zero, a line is drawn. If both majx and miny are 
zero, a point is drawn. The attributes which control the drawing of ellipses are the same as 
those attributes which control the drawing of circles and rectangles (namely, the perimeter and 
fill area attributes). 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

3.1.2. 7. elliptical_arc fCelliparc,/ 


Cerror @lliptical_arc (cl, sx, sy, ex, ©y, majx, miny) 

Ccoor *cl;/* center */ 

Cint sx,sy; /* starting point of arc */ 

Cint ex,ey; /* ending point of arc */ 

Cint majx, miny; /* endpoints of major and minor axes */ 

elliptical_arc draws an elliptical arc centered at cl with major(x) and minor (y) axes which 
terminate at majx and miny. Sx, sy and ex, ey are the starting and ending points of the arc. An 
error is generated (and the ellipse is not drawn) if the points (sx, sy , and ex, ey) are not on the 

10 Although the axes are called the major and minor axes by the standard they are really the x and y 
axes. In fact, the x-axis can either be the major or minor axis, depending on the relative length of the y-axis. 
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perimeter of the ellipse. Circular arcs are drawn in a counterclockwise manner. This convention 
is used to determine the difference between the arc formed by the obtuse angle determined by 
cl.z, cl.y , sx, sy , and ex, ey and the acute angle specified by these same points. Therefore 
switching the values of sx, sy and ex, ey will produce complementary arcs. 

If either majx or miny are zero, a line is drawn. If both majx and miny are zero, a point is 
drawn. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

65 EARCPNEL Arc points do not lie on ellipse. 

3 . 1 . 2 . 8 . el liptical_arc_close ^Celliparccl,/ 


Cerror elliptical_arc_close (cl, sx, sy, ex, ey, majx, miny, close) 

Ccoor *cl;/* center */ 

Cint sx,sy; /* starting point of arc */ 

Cint ex,ey; /* ending point of arc */ 

Cint majx, miny; /* enpoints of major and minor axes */ 

Cclosetyp© close; /* PIE or CHORD */ 

el liptical_arc_close draws an elliptical arc specified by sx, sy, ex, ey , and majx, miny 
The arc is closed with either the PIE or CHORD algorithm. The same restrictions on sx, sy, ex , 
and ey are applied to el liptical_arc_close as to el liptical_arc. However, 
el liptical_arc_close uses the fill area and perimeter attributes, whereas 
el liptical_arc_close uses the line attributes. 

If either majx or miny are zero, a line is drawn. If both majx and miny are zero, a point is 
drawn. In neither of these cases will any region be filled. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

65 EARCPNEL Arc points do not lie on ellipse. 

3.2. Raster Primitives 

Raster primitives include text, cell arrays, pixel arrays, and bitblts (bit block transfer). Bitblts 
are pixel arrays (bitmaps) which can be drawn using the various drawing modes. The current 
drawing mode determines how bitblt primitives are affected by information which is already on 
the screen. Raster primitives differ from geometrical primitives because their dimensions are not 
necessarily expressed in VDC Space. Therefore, you must be careful to consider whether position 
arguments are expressed in VDC Space or screen coordinates. 


8.2.1. text (Ctext) 
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Cerror text (cl, tstring) 

Ccoor^bl; /* starting point of text (in VDC Space) */ 

Cchar *tstring; /* text */ 

text displays the text contained in tstring at point cl (expressed in VDC Space). The appearance 
of text is controlled by the text attributes described in the next chapter; however, it is worth 
noting some of the effects of the most important attribute, text precision. The size of the text 
depends on the setting of the text precision (see the text_precision function) and the font 
selected. The results of clipping also depend on the text precision attribute (unless the text pre- 
cision is set to STROKE). Control characters are displayed as blanks, except in the SYMBOL font 
where they may be drawn as pictures of bugs. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

8 . 2 . 2 . vdm_text (Cvdmtextj 

Cerror vdm_text (cl, flag, tstring) 

Ccoor cl; /* starting point of text (in VDC Space) */ 

Ctext final flag; /* final text for alignment */ 

Cchar *tstring; /* text */ 

vdm_text displays the text contained in tstring at point cl (expressed in VDC Space). The 
intended difference between text and vdm_text is that vdm_text allows control characters; 
however, SunCGI does not handle control characters so text drawn with vdm_text will appear 
identical to text drawn with the text function. If the flag argument is equal to FINAL, the previ- 
ous text and the appended text are aligned separately. However, if the flag argument is equal to 
NOT_FINAL, the appended and previous text are aligned together. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

8 . 2 . 3 . append_text fCaptextj 

Cerror append_text (f lag, tstring) 

Ctextfinal flag; /* final text for alignment */ 

Cchar *tstring; /* text */ 

append_text displays the text contained in tstring after the end of the most recently written 
text. The type of text written depends on the same attributes which control the display of text. 
The flag argument determines whether the appended text is aligned with the previous text if the 
alignment is CONTINUOUS. If the flag argument is equal to FINAL, then the previous text and the 
appended text are aligned separately. However, if the flag argument is equal to NOT_FINAL, the 
appended and previous text are aligned together. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 


Revision A of 15 May 1985 


3-11 



Output 


SunCGI Reference Manual 


3 . 2.4 . inquir e_text_extent fCqtextext ) 


Cerror inquire_text_extent (tstring, nextchar, concat, lleft, uleft, uright) 
Cchar *tstring; /* text */ 

Cchar next char ; /* last character */ 

Ccoor *concat; /* concatenation point */ 

Ccoor * lleft, *ule£t, *uright; /* coordinates of 

text bounding box */ 

inquire_text_extent determines how large text fairing would be and where it would be 
placed if it were drawn using the current text attributes. The nextchar parameter is used to 
determine the point where text would start if more text (starting with nextchar ) were appended 
to the text specified by tstring 11 . If nextchar equals the last point of the current character is 
used. The argument concat returns the coordinates of the point where appended text would 
start. The arguments lleft, uleft, and uright return the coordinates of the bounding box of text 
contained in tstring. 

The values of lleft, uleft , and uright are defined by the bounding box of the character and there- 
fore may not be at the exact pixel where the character ends or begins. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

3.2.5 . cell_array (Ccellarr) 


Cerror cell__array (p, q, r, dx, dy, colorind) 

Ccoor *p, *q, *r; 

/* corners of parallelogram (in VDC Space) */ 

Cint dx,dy; /* dimensions of color array */ 

Cint *colorind; /* array of color values */ 

cell_array draws a scaled and skewed pixel array on the view surface(s). Points p, g,and r 
(expressed in VDC Space) define a parallelogram. Line p-q is a diagonal and p is the lower left- 
hand corner, r is one of the remaining two corners, dx and dy define the width and the height 
of the array colorind which is mapped onto the parallelogram defined by p,q, and r. 

cel l_array is one of the few primitives which depends on the actual size of the view surface. 
Cell arrays are not drawn if the elements of the array would be smaller than one pixel. How- 
ever, because different view surfaces may have different dimensions, a cell array might be drawn 
on one view surface, but not on another smaller view surface. Finally, all cells composing the 
cell array are the same size; therefore, the upper left hand corner of the cell array might be 
down and to the right of point q because of the accumulated error of making all of the cells 
slightly smaller than their floating point size. For example if each cell of a three-by-three cell 
array is supposed to be 3.333 pixels wide, the actual cell array will be nine pixels wide instead of 
ten. 

ERRORS: 


11 This is a method for accounting for proportional spacing. 
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4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

66 ECELLATS Cell array dimensions dx,dy are too small. 

67 ECELLPOS Cell array dimensions must be positive. 

8.2.6. pixel_array (Cpixarr,) 

Cerror pixel_array (peel 1 , m, n , color ind) 

Ccoor ‘pcell ; /‘ base of array in VDC Space */ 

Cint m ( n; /* dimensions of color array in screen space */ 

Cint ‘colorind; /* array of color values */ 

pixel_array draws array colorind starting at point pcell (expressed in VDC Space), m and n 
(expressed in screen space) define the x- and y-dimensions of the array. Therefore, pixel arrays 
always have a constant physical size, independent of the dimensions of VDC Space. The pixel 
array is drawn down and to the rsght from point pcell. If either m or n are not positive, the 
absolute value of m and n are used. pixel_array is not affected by the current dramng 
mode. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

69 EVALOVWS Value outside of view surface. 

8.2.7. bitblt_source_array (Cbtblsouarr,) 

Cerror bitblt_source_array (pixsource, xo, yo, xe, ye, pixtarget, xt, yt, name) 
Cpixrect ‘pixsource, ‘pixtarget; /* source and target pixel arrays */ 

Cint xo,yo; /* coordinates of source pixel array (in VDC Space) */ 

Cint xe,ye; /* dimensions of source pixel array (in screen space) */ 

Cint xt,yt; /* coordinates of target pixel array (in VDC Space) */ 

Cint name; /* view surface name */ 

bitblt_source_array moves a pixel array from point ( xo,yo ) to point (xt,yt) using the 
current drawing mode. Both of these points are expressed in VDC Space. The size of the pixel 
array is determined by the xe and ye arguments which are expressed in screen space. Pixsource 
and pixtarget are pixrects 12 which contain the bitmaps at the source and target destinations. An 
error is detected if either xe or ye are not positive. If the replicated pattern array overlaps with 
the source array on the screen, the visual result depends on the current drawing mode, pix- 
source and pixtarget may have different contents depending on the screen drawing mode (see the 
set_drawing_mode function). 

Multiple view surfaces and bitbit’s are incompatible, so a name argument must be specified. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

12 Refer to the Programmers’ Reference Manual for Sun Windows for more information about pixrects. 
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69 EVALOVWS Value outside of view surface. 


3.2.8. bitblt_pattern_array fCbtblpatarr^ 

Cerror bitblt_pattern_array (pixpat , px, py, pixtarget, rx, ry, 
ox, oy, dx, dy, nam©) 

Cpixrect *pixpat; /* pattern source array */ 

Cint px,py; /* pattern extent V 

Cpixrect *pixtarget; / & destination pattern array */ 

Cint rx,ry; /* pattern reference point */ 

Cint ox,oy; /* destination origin A / 

Cint dx,dy; /* destination extent */ 

Cint name; /* view surface nam© */ 

bitblt__pattern_array replicates the pattern (using the current drawing mode) stored in 
pixpat to fill the area of array pixtarget which is determined by oz, oy, and dx, dy. The pattern 
reference point determines the offset of pattern array from the point zero. The resultant pattern 
array is displayed at ox, oy. If the replicated pattern array overlaps with the source array on 
the screen, the visual result depends on the current drawing mode. 

Pixpat is a pointer to a pixrect which must be created by the application program. If pixpat is 
not a pointer to an existing pixrect, an error is generated. Pixtarget is a pointer to a pixrect 
which is created by a bitblt_pattern_array. 

Multiple view surfaces and bitblt’s are incompatible, so a name argument must be specified. 
ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

69 EVALOVWS Value outside of view surface. 

70 EPXNOTCR Pixrect not created. 

3.2.9 . bitblt_patterned_source_array ^Cbtblpatsouarr^ 

Cerror bitblt_patterned_source_array (pixpat , px, py, pixtarget, rx, ry, 
pixsource, sx, sy, ox, oy, dx, dy, name) 

Cpixrect *pixpat; /* pattern source array */ 

Cint px,py; /* pattern extent */ 

Cpixrect *pixsource; /* source array */ 

Cint sx,sy; /* source origin */ 

Cpixrect ^pixtarget; /* destination pattern array */ 

Cint rx,ry; /* pattern reference point */ 

Cint ox,oy; /* destination origin */ 

Cint dx,dy; /* destination extent */ 

Cint name; /* view surface nam© */ 

bi*tblt_patterned_source_array replicates the pattern (using the current drawing mode) 
stored in pixpat to fill the area of array pixtarget which is determined by oz, oy, and dx, dy. The 
replicated pattern array is ANDed into the pixrect pointed to by pixsource before the array is 
copied to pixtarget. The pattern reference point determines the offset of pattern array from the 
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point zero. The resultant pattern array is displayed at ox, oy. If the replicated pattern array 
overlaps with the source array on the screen, the visual result depends on the current drawing 
mode. Pixpat is a pointer to a pixrect which must be created by your application program. 
Pixsource and pixtarget are pointers to pixrects which are created by a 
bitb 1 t_patterned_source_arr ay. 

Multiple view surfaces and bitblt’s are incompatible, so a name argument must be specified. 
ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

69 EVALOVWS Value outside of view surface. 

70 EPXNOTCR Pixrect not created. 

8.2.10. inquire_cell_array fCqcellarry 


Cerror inquire_cell_array (name, p, q, r, dx, dy, colorind) 

Cint name; /* view surface name */ 

Ccoor *p, *q, *r; /* corners of parallelogram 

(in VDC Space) */ 

Cint dx , dy ; /* dimensions of color array */ 

Cint ‘colorind; /* array of color values */ 

Points p, g,and r (in VDC Space) define a parallelogram with line p-q as the diagonal where p is 
the lower left-hand corner, r is one of the remaining two corners, dx and dy define the width 
and the height of the array colorind which contains the colors of the pixels on the screen which 
lie within the parallelogram defined by p,q, and r. Notice that a view surface identifier, name, 
must be specified because the result of this function is highly dependent on the dimensions and 
contents of the view surface. 

The area of the screen corresponding to the parallelogram is assumed to contain a regular grid of 
points. However, if each element of the grid is larger than one pixel, the color of the pixel at 
lower left-hand corner of each element of the grid is defined to be the color of the grid element. 
Therefore, the values contained in colorind are highly dependent on the size of the view surface. 
An error is produced if the elements of the grid are smaller than one pixel. 

ERRORS: 


4 

ENOTVSAC 

CGI not in proper state: CGI shall be in state VSAC. 

10 

EVSIDINV 

Specified view surface name is invalid. 

13 

EVSNOTOP 

Specified view surface not open. 

15 

EVSNTACT 

Specified view surface is not active. 

66 

ECELLATS 

Cell array dimensions dx,dy are too small. 

67 

ECELLPOS 

Cell array dimensions must be positive. 
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3 . 2 . 11 . inquire_pixel_array fCqpixarrj 

Cerror inquir©_pixel_array (p, m, n, color ind, name) 

Ccoor ^p; /* bas© of array in VDC Space */ 

Cint m,n; /* dimensions of color array in screen space */ 

Cint *colorind; /* array of color values */ 

Cint name; /* view surface name */ 

inquire_pixel_array fills array colorind with the values of pixels in the area of the screen 
defined by point p (expressed in VDC Space) and m and n (expressed in screen space). The array 
is filled down and to the right from point p. If either m or n are not positive, the absolute value 
of these arguments is used. 

Multiple view surfaces and bitblt’s are incompatible, so a name argument must be specified. 
ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

69 EVALOVWS Value outside of view surface. 

70 EPXNOTCR Pixrect not created. 

3 . 2 . 12 . inquire_device_bitmap ^Cqdevbtmp^ 

Cpixrect *inquire_device_bitmap (name) 

Cint name; / 6 name assigned to cgi view surface */ 

inquire_device_bitmap returns the pixrect which corresponds to the view surface. If you 
want to use subareas of this pixrect or manipulate it any other way, refer to the Pixrects 
Chapter in the Programmers 1 Reference Manual for Sun Windows. Pixrects may be created in 
other manners; again refer to the Pixrect Chapter in the Programmers 1 Reference Manual for 
Sun Windows. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in in state VDOP, VSOP, or 

VSAC. 


3 . 2 . 13 . inquire_.bitblt_alignments (fcqbtbl align/ 

Cerror inquire_bitblt_alignments (base, width, px, py, maxpx, maxpy, name) 
Cint *base; / A bitmap bas© alignment * / 

Cint ^width; /* width alignment */ 

Cint *px, *py; /* pattern extent alignment */ 

Cint *maxpx, *maxpy; /* maximum pattern size */ 

Cint name; / & name assigned to cgi view surface */ 

inquire_bitblt_alignments reports the alignment criteria which are necessary for some 
implementations. These factors are not critical for SunCGI. However, you should keep in mind 
the appropriate depth for the pixrect when talking to a specific device. Therefore the arguments 
base, width, px , and py are always set to zero. The arguments maxpx and maxpy are device 
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dependent and determine the maximum size of a pattern for bitblt_pattern_array and 
bitblt_patterned_sourco_array. 

Multiple view surfaces and bitbit’s are incompatible, so a name argument must be specified. 
ERRORS: 


4 

ENOTVSAC 

CGI not in proper state: CGI shall be in state VSAC. 

10 

EVSIDINV 

Specified view surface name is invalid. 

13 

EVSNOTOP 

Specified view surface not open. 

15 

EVSNTACT 

Specified view surface is not active. 


3.3. Drawing Modes 

Drawing modes determine the result of drawing any output primitive on the clear screen (back- 
ground) or on top of a previously drawn object. Drawing modes only affect the drawing of bitblt 
primitives. However, a non-standard set_global_drawing_mode function is provided, 
which affects all output primitives except bitblt’s. Resetting the drawing mode in the middle of 
an application program only affects those output primitives drawn after the mode is reset. The 
novice user is advised not to reset the drawing mode until the user has written at least one appli- 
cation program using SunCGI. 


3.3. 1. set__dr awing_mode (Csdr awmode ) 


Cerror set__drawing_mode (visibility, source, destination, combination) 
Cbmode visibility; / ft transparent or opaque */ 

Cbitmaptype source; /* NOT source bits */ 

Cbitmaptype destination; /* NOT destination bits */ 

Ccombtype combination; /* combination rules */ 

set_drawing_mode determines the current drawing mode which in turn determines how bitblt 
primitives are displayed. The visibility argument determines how pixels with index zero are 
treated. 

typedef enum { 

TRANSPARENT, OPAQUE 
} Cbmode; 

typedef enum { 

BITTRUE, BITNOT 
} Cbitmaptype; 

typedef enum { 

REPLACE, AND, OR, NOT, XOR 
y Ccombtype; 

If visibility is set to TRANSPARENT, all source pixels with index zero leave the destination pixel 
unchanged, regardless of the operation, whereas if visibility is set to OPAQUE, all pixels are 
treated normally. The arguments source and destination determine whether the contents of the 
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source and destination pixrects are NOTted before the bitbit operation is performed. 

The combination argument determines how the source and destination pixrects are combined. 
If combination is equal to REPLACE, the source pixrect (after optionally being NOTted) replaces 
the destination pixrect. If combination is equal to AND, OR, NOT, or XOR the source pixrect and 
the destination pixrect are combined in the indicated Boolean fashion. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in in state VDOP, VSOP, or 
VS AC. 


3.3.2. set_global_drawing_mode (Csgldravnnodej 

Cerror set_global_drawing_mode (combination) 

Ccombtype combination; /* combination rules */ 

set_global_drawing_mode determines the current global drawing mode which in turn deter- 
mines how all output primitives except bitbit’s are displayed. The combination argument deter- 
mines how the source and destination pixrects are combined. If combination is equal to REPLACE 
(the default value) the output primitive replaces the destination background. If combination is 
equal to AND, OR, or XOR the output primitive and the information on the screen are combined in 
the indicated Boolean fashion. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in in state VDOP, VSOP, or 
VS AC. 


3.3.3. inquire_drawing_mode (Cqdrawmode^ 

Cerror inquire_drawing_mode (visibility ( source, destination, combination) 
Cbmode ‘visibility; /* transparent or opaque */ 

Cbitmaptype ‘source; /* NOT source bits */ 

Cbitmaptype ‘destination; /* NOT destination bits */ 

Ccombtype ‘combination; /* combination rules */ 

The inquire_drawing_mode returns the values of the four components of the current draw- 
ing mode. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in in state VDOP, VSOP, or 
VSAC. 
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The current attributes determine how output primitives are displayed. Attributes are not 
specific to any view surface, but affect all view surfaces. If you want to avoid using the attribute 
functions, the current attributes are set to their default attributes which are defined in Table 4- 
1. The current attributes may be set either individually or in groups (by changing the index into 
the bundle table). Each entry in the bundle table specifies a set of attributes for a particular 
type of primitive (for example, solid objects). The method for setting the current attributes 
depends on the state of the ASF ( aspect source flag) for each attribute. For individual attribute 
functions to have an effect, the ASF must be set to INDIVIDUAL. If the ASF is set to BUNDLED, the 
current attribute is defined by the entry in the bundle table pointed to by the bundle index. 

The majority of this chapter is devoted to individual attribute functions. Individual attribute 
functions are grouped according to the output primitives they effect: polylines, polymarkers, 
filled objects, and text. The color^table function (which redefines color table entries) is also 
included in this chapter. Finally, functions for obtaining the values of the current attributes are 
discussed. 
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Table 4-1: Default Attributes 


Attribute 

Value 

Attribute 

Value 

All ASFs 

INDIVIDUAL 

All Bundle Indices 

1 

Line Type 

SOLID 

Line Endstyle 

POINT 

Line Width Specification Mode 

SCALED 

Line Width 

0.0 

Line Color 

1 



Marker Size Specification Mode 

SCALED 

Marker Size 

0.0 

Marker Color 

1 



Fill Style 

HOLLOW 

Fill Visible 

ON 

Fill Color 

1 

Fill Hatch Index 

0 

Fill Pattern Index 

1 

Number of Pattern Table Entries 

2 

Pattern Reference Point 

0,0 

Pattern Size 

300,300 

Perimeter Style 

SOLID 

Perimeter Width Specification Mode 

SCALED 

Perimeter Width 

0.0 

Perimeter Color 

1 

Fontset 

1 

Current Font 

STICK 

Text Precision 

STRING 

Character Expansion Factor 

1.0 

Character Space 

0.1 

Character Color 

1 

Character Height 

1000 

Character Base. 2 

0.0 

Character Base.j/ 

0.0 

Character Up.x 

1.0 

Character Up.y 

1.0 

Character Path 

RIGHT 

Horizontal Text Alignment 

NRMAL 

Vertical Text Alignment 

NORMAL 

Text Continuous Alignment . x 

1.0 

Text Continuous Alignment . y 

1.0 


4.1. Bundled Attribute Functions 

The attribute environment selector functions determine if the current attributes are defined indi- 
vidually or by using a set of attributes (bundles). Bundles are defined by entries in the bundle 
table. The CGI standard specifies the bundle table as read-only but SunCGI allows user- 
definition of entries in the bundle table. 


4.1.1. set_aspect_source_flags (Csaspsouf lags^ 


Cerror set_aspect_source_f lags (flags) 

Cflaglist * flags; /* list of ASFs */ 
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set_aspect_source_ flags determines whether individual attributes are set individually or 
from bundle table entries. 

typed© f struct { 

Cint n; 

Cint num[]; 

Casptyp© value []; 

> Cflaglist; 

The n element of the flags argument determines how many flags are to be set. The num 
array of the flags argument determines which flags are to be set. Flag numbers are provided 
in Table 4-2. Finally, the value array of the flags argument determines the values of the flags 
specified in num. If a value is assigned to INDIVIDUAL, the individual attribute functions affect 
the current attribute. If the value of index is BUNDLED, calls to individual attribute functions 
have no effect . The default bundle index is set to 1 (which initially contains the default value for 
the attributes specified in Table 4-1). The default value of all aspect source flags is INDIVIDUAL. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 


Table 4-2: Attribute Source Flag Numbers 


Flag Attribute 

Flag Attribute 

0 line type 

1 line width 

2 line color 

3 marker type 

4 marker width 

5 marker color 

6 interior style 

7 hatch index 

8 pattern index 

9 fill color 

10 perimeter type 

11 perimeter width 

12 perimeter color 

13 text font index 

14 text precision 

15 character expansion factor 

16 character spacing 

17 text color 


4.1.2. define_bundle_index /tdefbundix^ 


Cerror def ine_bundle_index (index, entry) 

Cint index; /* entry in attribute environment table */ 

Cbunatt Gentry; /* new attribute values */ 

defin@_bundle_index is a nonstandard function which defines an entry in the bundle table. 
The type Cbunatt is a structure which contains elements corresponding to all the attributes. If 
the contents of a bundle table entry are changed, all subsequently drawn primitives use the infor- 
mation in the new entry. You should keep this fact in mind if you are designing display list 
traversal algorithms using SunCGI. 
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typed© f struct { 

Cl intype lin@_type; 

C float lin©_width; 

Cint line_color; 

Cmartyp© marker __typ© ; 

C float marker_siz©; 

Cint mar ker _co 1 or ; 

Cintertype inter ior_styl© ; 

Cint hatch_index; 

Cint pattern_index ; 

Cint fill__color; 

Cl intype perimeter_type; 

C f 1 oat per imet er_width ; 

Cint perimeter^ color ; 

Cint text_font; 

Cprectype text_precision; 

C float char acter_expans ion; 

C float character_spacing; 

Cint text_color; 

} Cbunatt; 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
31 EBBDTBDI Bundle table index out of range. 

4.2. Line Attributes 

SunCGI provides for specifying the style, width and color of lines which constitute poly lines, 
rectangles, circular arcs, and elliptical arcs. The functions do not affect the drawing of the per- 
imeter of polygon*, rectangles, circles, or ellipses. The attributes of the perimeters of solid 
objects are set by the perimeter functions. 

4-2.1. polyline_bundle_index /tpolylnbundix^ 

Cerror polyline_bundle_index (index) 

Cint index; /* polyline bundle index */ 

polyline_bundle_index sets the current polyline bundle index to the value of index. The 
contents of the polyline_bundle_index are line type, line width and line color. The line 
width specification mode and the line_endstyle function are not included in the polyline 
bundle. If index is not defined, an error is generated, and the polyline_Jbundle_index does 
not change. If the ASF’s for any of these attributes is set to BUNDLED, the current values of these 
attributes are set to the contents of the bundle. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
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33 EBADLINX Polyline index is invalid. 
4-2.2. line_type ^Clntypej 


Cerror line_type (ttyp) 

Clintyp© ttyp; /* styl© of line */ 

The styles of line offered are SOLID, DASHED, DOTTED, D ASHED_D OTTED , and DASH_DOT_D OTTED. 
The default line style is SOLID. The actual representation of a line on the screen is affected by 
the line endstyle. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
30 EBTBUNDL ASF is BUNDLED. 

4-2.3. line_endstyle fClnendstylej 


Cerror line_endstyl© (ttyp) 

Cendstyl© ttyp; /* styl© of line */ 

line__endstyle determines how a textured (non-SOLID) line terminates. The three values 
which ttyp can assume are NATURAL, POINT, and BESTJFIT. If the endstyle selected is NATURAL, 
the last component of the line texture (for example, a dash or a dot) which can be completely 
drawn is drawn. Blank space at the end of the line may cause the dine to not appear as long as 
specified by the starting and ending coordinates. If the endstyle selected is POINT, the last point 
of the line is drawn whether it is appropriate or not. In this case, the endpoints of the line 
always appear on the screen. If the endstyle selected is BESTJTT, the last point is always drawn 
but is extended as far back as the last space if appropriate. However, the BESTJTT endstyle may 
shorten the space between the last element of the line and the element preceding the last ele- 
ment by one in order to guarantee that the line ends on a drawn point. The default endstyle is 
BESTJTT. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
4 - 2 . 4 - 1 ine_width_speci f icat ion_mode (fclnwidthspecmode ) 


Cerror line_width_specif ication_mode (mode) 

Cspecmod© mod©; /* pixels or percent */ 

line_width_specification_mode allows the line^width to be specified in pixels or as a per- 
centage of VDC Space according to the value of mode (which can either be ABSOLUTE or SCALED). 
If the line width specification mode is changed from ABSOLUTE to SCALED, the change in the line 
width will probably be dramatic. 
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If multiple view surfaces are open, the line width is calculated on the basis of the first view sur- 
face opened. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
4-2.5. line_width (Clnwidth) 


Cerror line_width (index) 

C float index; / 4 line width */ 

line_width determines the width of the lines composing polylines, circular arcs, etc. If the 
line_width_8pecification_mode is SCALED, index is expressed in percent of VDC Space and if the X 
and Y dimensions are different, the width is calculated on the basis of the range of the x- 
coordinate of VDC space. If the parameter setting would result in a line less than one pixel wide, 
the line width is displayed as one pixel wide. The default line width is 0.0 (SCALED). 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
30 EBTBUNDL ASF is BUNDLED. 

34 EBDWIDTH Width must be nonnegative. 

4-2.6. line_color (Clncolor^ 


Cerror line_color (index) 

Cint index; /* line color */ 

line_color resets the color of the lines, index selects an entry in the color lookup table. The 
default value of index is 1. 

ERRORS: 


5 

ENOTOPOP 

CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 

30 

EBTBUNDL 

ASF is BUNDLED. 

35 

ECINDXLZ 

Color index is less than zero. 

36 

EBADCOLX 

Color index is invalid. 

X 

Polymarker 

Attributes 


The type, size and color of markers (the components of polymarkers) are controlled by the fol- 
lowing functions. 
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4.8.1. polymarker_bundle_index (fcpolymkbundixj 


Cerror polymarker _bundle_index (index) 

Cint index; /* polymarker bundle index */ 

polymarker_bundle_index sets the current polymarker bundle index to the value of index. 
The contents of a polymarkerjbundle are marker type, marker width and marker color. 
The marker size specification mode function is not included in the polymarker bundle. If index 
is not defined, an error is generated, and the polymarker_bundle_index does not change. If the 
ASF’s for any of these attributes is set to BUNDLED, the current values of these attributes are set 
to the values of the corresponding attribute in the bundle. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
37 EBADMRKX Polymarker index is invalid. 

4 . 8 . 2 . marker _type (Cmktype^ 


Cerror marker_type (ttyp) 

Cmartype ttyp; /* style of marker */ 

marker_type sets the marker type to one of five marker types DOT, PLUS, ASTERISK, CIRCLE, or 
X. Be sure to use an argument of Cmartype and not Cint. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
30 EBTBUNDL ASF is BUNDLED. 

4 - 8 . 3 . marker _size_specification_mode /Cmksizespecmode^ 

Cerror marker_size_specification_mode (mode) 

Cspecmode mode; /* pixels or percent */ 

marker_size_specification_mode allows the marker_size to be specified in pixels or as a 
percentage of VDC Space according to the value of mode (which can either be ABSOLUTE or 
SCALED). 

If multiple view surfaces are open, the marker size is calculated on the basis of the first view sur- 
face opened. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
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4.3.4- marker_size fCmksize/ 


Cerror marker_size (index) 

C float index; /* marker size */ 

marker.size sets the size of the marker height and marker width, index is expressed in per- 
cent of VDC Space. The default marker size is 4 percent of VDC space. If the marker size 
becomes very small, markers of all types are displayed as points. An error is detected if index is 
negative. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
38 EBADSIZE Size must be nonnegative. 

4-3.5. marker_color (Cwkcolor) 


Cerror marker _co lor (index) 

Cint index; /* marker color */ 

marker_color resets the color of the markers, index selects an entry in the color lookup table. 
An error is detected if index is not between 0 and 255. 

ERRORS: 


5 

ENOTOPOP 

CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 

30 

EBTBUNDL 

ASF is BUNDLED. 

35 

ECINDXLZ 

Color index is less than zero. 

36 

EBADCOLX 

Color index is invalid. 


4.4. Solid Object Attributes 

The solid object attribute functions describe how all solid object primitives are filled (colored-in). 
There are three sets of solid object attribute functions: 

fill area attributes 

determine the general method for ‘coloring-in’ solid geometrical objects. 

pattern attributes 

determines a pixel array for filling a polygon if the fill style is set to PATTERN. 
perimeter attributes 

determine how the edge of a geometrical object is displayed if the perimeter visibility 
is ON. 
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4.4.I. Fill Area Attributes 

The fill area attribute functions determine the general method for drawing polygons, filled rec- 
tangles, circles, and ellipses. 

4.4 I I . fill_area_bundle_index (Zt lareabundix^ 


Cerror f ill_area_bundle_index (index) 

Cint index; /* fill area bundle index */ 

fill_area_bundle_index sets the current fill area bundle index to the value of index. The 
contents of the fill_area_bundle are interior style, fill color, hatch index, pattern index, 
perimeter type, perimeter width and perimeter color. The perimeter width specification mode 
and the pattern attributes are not included in the definition of the filLarea bundle. If index is 
not defined, an error is generated, and the filLarea^bundle^index does not change. If the ASF’s 
for any of these attributes is set to BUNDLED, the current value of the attribute is set to the 
value of the corresponding attribute in the bundle. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 

39 EBADFABX Fill area index is invalid. 

4-4 -1-2. irvterior_st:yl© ^Cintstylej 


Cerror inter ior__style (istyle, perimvis) 

Cintertype istyle; /* fill style */ 

Cflagtype perimvis; /* perimeter visibility */ 

irvterior_sty le sets the fill style for solid objects to either HOLLOW, SOLIDI, PATTERN, or 
HATCH. If the fill style is set to SOLIDI, the solid object is filled with the current fill color. How- 
ever, the appearance of the solid object on the screen depends on the drawing mode. If tstyle is 
set to PATTERN or HATCH, the solid object is filled with the current PATTERN or HATCH style. 
The PATTERN and HATCH styles are explained in the pattern attributes section. The default fill 
style is HOLLOW. 

interior_style also determines whether the perimeter of the solid object is visible according 
to the value of perimvis (which must be ON or OFF). If perimvis is OFF, the perimeter attributes 
have no effect. The default value of perimeter visibility is ON. 

Be careful when using the interior style function to explicitly specify the perimvis argument. If 
you do not specify it, or set it to OFF, the geometrical output primitive may not be displayed 
because the interior style is HOLLOW. 


ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
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4 . 4 . 1.3. fill_color (Cflcolor; 


Cerror fill_color (color) 

Cint color; /* color for solid object fill */ 

fill_color determines the color for filling solid objects, if the fill style is not set to HOLLOW. 

The default fill style is HOLLOW, so changing the fill color will not have an effect without chang- 
ing the interior style first. 

The default fill color is 1. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 

35 ECINDXLZ Color index is less than zero. 

36 EBADCOLX Color index is invalid. 

4-4- 2. Pattern Attributes 


Geometrical primitives can be filled with two dimensional arrays of color values called patterns. 
SunCGI supports pre-defined as well as user-defined patterns. The definition of patterns is 
stored in the pattern table. Each entry in the pattern table consists of a two-dimensional array 
of color values and the X and Y dimensions of the array. The starting position (lower left-hand 
corner) of the pattern is determined by the pattern reference point. 

Two types of patterns are available: PATTERNS and HATCHes. PATTERNS can be scaled and 
translated. HATCHes can’t and simply fill the geometrical output primitives with pixel arrays. 


4 - 4 - 21 . hatch_index (Chatchixy 


Cerror hatch_index (index) ; 

Cint index; /* index in the pattern table bound to HATCH */ 

hatch_index determines which index in the pattern table is used to fill solid objects when the 
fill style is set to HATCH. The default hatch index is 1. An error is generated if index points to 


an undefined entry in 

ERRORS: 

the pattern table. 

5 

ENOTOPOP 

CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 

30 

EBTBUNDL 

ASF is BUNDLED. 

42 

ESTYLLEZ 

Style (pattern or hatch) index is less than zero. 

43 

ENOPATNX 

Pattern table index not defined. 
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4-\.2.2. pattern. index fCpatix^ 


Cerror pattern_index (index) ; 

Cint index; /* index in the pattern table bound to PATTERN */ 

pattern_index determines which index in the pattern table is used to fill solid objects when 
the fill style is set to PATTERN. pattern_index also determines the pattern which is used by 
drawing mode. The default pattern index is 2. An error is generated if index points to an 
undefined entry in the pattern table. Note that pattern_index 0 is not defined. 


ERRORS: 

5 ENOTOPOP 
30 EBTBUNDL 

42 ESTYLLEZ 

43 ENOPATNX 


CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
ASF is BUNDLED. 

Style (pattern or hatch) index is less than zero. 

Pattern table index not defined. 


j.4-2.8. pattern.table (Cpattable^ 


Cerror pattern_table (index, m, n, colorind) 

Cint index; /* entry in table */ 

Cint m,n; /* number of rows and columns */ 

Cint *colorind; /* array containing pattern */ 


pattern_table defines an entry in the pattern table, index defines the entry in the table 
(which must be less than 10). An error is generated if index is outside the bounds of the pattern 
table, m and n define the height and width of the pattern (in pixels). The array pointed to by 
the argument colorind contains the actual pattern. All nonzero entries in colortnd are set to 1. 
Pattern 1 is initially defined to be a three-by-three matrix which is set to zero at the corners and 
one elsewhere. Pattern 1 produces simple cross-hatching. Pattern 2 (which produces a polka-dot 
pattern) is initially defined to be a three-by-three matrix which is set to 1 at the center and 0 
elsewhere. The maximum number of elements in a pattern is 256. 


ERRORS: 

5 ENOTOPOP 

40 EPATARTL 

41 EPATSZTS 

42 ESTYLLEZ 
44 EPATITOL 


CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
Pattern array too large. 

Pattern size too small. 

Style (pattern or hatch) index is less than zero. 

Pattern table index too large. 


\.\.2.\. pattern_reference_point (Cpatrefpt^ 
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Cerror pattern_r©f@rence__point (begin) 

Ccoor *begin; 

patterns e f erence.point defines the point in VDC Space where the pattern box begins. 
begin determines the offset of the pattern. pattern_reference_point has no effect if the interior 
style is set to HATCH. The lower left-hand corner of the pattern box is determined by begin. The 
pattern is conceptually replicated over all of VDC Space — the begin point provides for fine posi- 
tioning of the pattern. The default pattern reference point is (0,0). 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 

4 . 4 - 2 . 5 . pattern_size /Cpatsize,/ 


Cerror pattern_size (dx , dy) 

Cint dx,dy; /* size of pattern in VDC Space */ 

pat:tern_size defines the size of the pattern array in VDC coordinates, dx and dy determine 
the size of an element of the pattern in VDC Space. pattern_size therefore allows you to ‘stretch’ 
the pattern to a certain size. If dx or dy would result in pattern elements less than one pixel 
wide, an error is generated and the pattern size is set m pixels by n pixels. 13 If the pattern size is 
larger than the bounds of screen space, the effective pattern size is the size of VDC Space. The 
default pattern size is 300,300. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
4.4.8. Perimeter Attributes 

As mentioned previously, control of the drawing of the borders of solid objects is under the con- 
trol of the perimeter attribute functions, not the line attribute functions. However, the two sets 
of functions perform the same tasks. Perimeter attribute functions have no effect if the perime- 
ter visibility is set to OFF. The perimeter attributes are essentially the same as the line attri- 
butes except that they affect the borders of solid attributes. Which attributes affect which prim- 
itives may become ambiguous when the interior style is set to HOLLOW. 


4. 4.8.I. perimeter__type /Cperirntypej 


Cerror perimeter_type (ttyp) 

Clintype ttyp; /* style of perimeter */ 

The styles of perimeter offered are SOLID, DASHED, DOTTED, DASHED_DOTTED, and 
DASHJ>OT_DOTTED. The default perimeter style is SOLID. The actual representation of a 


1S m and n are obtained from the pattern table. 
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perimeter is effected by drawing mode as well as the perimeter style. Notice that there is no 
ending style for perimeter. The endstyle is controlled by the line endstyle function. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
30 EBTBUNDL ASF is BUNDLED. 

4. 4. 3. 2. perimeter_width (Cperimwidth) 


Cerror perimeter_width (index) 

Cfloat index; /* perimeter width */ 

perimeter_width determines the width of the perimeters of solid objects. Index can be 
expressed in percent of VDC Space or pixels. If the perimeter width specification mode is set to 
SCALED and the x and y dimensions are different, the perimeter width is calculated on the basis 
of the range of the x-coordinate of VDC space. If the parameter setting would result in a perime- 
ter less than one pixel wide, the perimeter width is displayed as one pixel wide. The default per- 
imeter width is 0.0 (SCALED). 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
30 EBTBUNDL ASF is BUNDLED. 

34 EBDWIDTH Width must be nonnegative. 

4-4 -3.3. perimeter_width_specification_mode (Cperimwidthspecmode^/ 


Cerror perimeter_width_specif ication_mode (mode) 

Cspecmode mode; /* pixels or percent */ 

perimeter_width_specification_mode allows the perimeter_vidth to be specified in 
pixels or as a percentage of VDC Space according to the value of mode (which can either be 
ABSOLUTE or SCALED). If the perimeter width specification mode is changed from ABSOLUTE to 
SCALED, the change in the line width will probably be dramatic. 

If multiple view surfaces are open, the perimeter width is calculated on the basis of the first view 
surface opened. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
4-4-2-4- perimeter_color (Cperimcolor^ 


Cerror per imeter_co lor (index) 

Cint index; /* perimeter color */ 
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perimet:er_color resets the color of the perimeters, index selects an entry in the color 
lookup table. The default value of index is 1. An error is detected if index is not between 0 and 


255. 

ERRORS: 


5 

ENOTOPOP 

CGI not in proper state CGI shall 

30 

EBTBUNDL 

ASF is BUNDLED. 

35 

ECINDXLZ 

Color index is less than zero. 

36 

EBADCOLX 

Color index is invalid. 


be in state VDOP, VSOP, or VSAC. 


4.5. Text Attributes 

SunCGI provides a variety of functions for determining how text is written to the screen. The 
most important text attribute is text precision. If text precision is set to STRING, firmware char- 
acters are used. The fonts, size, spacing, and alignment of firmware are more limited than char- 
acters drawn with text precision set to a value other than STRING. Therefore, calls to text attri- 
bute functions regulating these aspects of text drawing have no effect when text precision is set 
to STRING. 

4-5.1. text_bundle_index ^Ctextbundixj 


Cerror text_bundle_index (index) 

Cint index; /* text bundle index */ 

t:ext_bundle_index sets the current text bundle index to the value of index. The contents of 
the text bundle index are text font text precision , character expansion factor , character spacing y 
and text color . The character height , character orientation, character path, text alignment and 
fixed font are not included in the definition of the text bundle. If index is not defined, an error is 
generated, and the text bundle index does not change. If the ASF’s for any of these attributes are 
set to BUNDLED, the current values of these attributes are set to the contents of the bundle. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 

45 EBADTXTX Text index is invalid. 

4-5.2. t:ext_precision (Ctextprec) 


Cerror text_precision (ttyp) 

Cprectype ttyp; /* text type */ 

*text_precision controls the type of text displayed, ttyp can assume one of three values: 
STRING, CHARACTER, or STROKE. If the text precision is set to STRING, the firmware character 
set is used. 
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Firmware characters cannot be scaled or rotated. 

Characters are clipped, but not in parts (that is, if any portion of the character exceeds the clip- 
ping boundary the whole character is clipped). If the text precision is set to CHARACTER, 
software generated characters are employed. All text attributes have a visible effect on software 
generated characters, but according to the standard, text drawn with CHARACTER precision are 
not clipped in parts. However, in SunCGI, characters are clipped in parts. If the text precision 
is set to STROKE, the CHARACTER precision capabilities are enabled and characters are clipped in 
parts. The default text precision is STRING. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
30 EBTBUNDL ASF is BUNDLED. 

4.5.3. character _set_index fCcharsetix^ 


Cerror character_set_index (index) 

Cint index; /* font set */ 

character_set_index selects a set of fonts. Although SunCGI supports this function, only 
set number 1 is defined. Calls to character_set_index with index assigned to a value other than 1 
are ignored. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
4 . 5 . 4 . text_font_index fCtext fontixj 


Cerror text_font_index (index) 

Cint index; /* font */ 

text_font_index resets the current font. A list of available fonts and their availability when 
text precision is set to STRING is given in Table 4-3. A warning about the SYMBOL font: 
undefined characters are displayed as bugs (the six-legged kind). The default font is STICK. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
30 EBTBUNDL ASF is BUNDLED. 

47 ETXTFLIN Text font is invalid. 
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Table 4-3: Available Fonts 


Font 

Available in String Precision ? 

ROMAN 

YES 

GREEK 

YES (displayed as STICK font) 

SCRIPT 

YES 

OLDENGLISH 

NO 

STICK 

YES 

SYMBOLS 

NO 


4-5.5. character _expansion_factor ^Ccharexpfac/ 


Cerror character _expansion_factor (efac) 

Cfloat efac; /* width factor */ 

character_expansion_ factor determines the width- to-height ratio of characters. If efac is 
greater than 1 the characters appear fatter than they are wide. If efac is less than 1 the charac- 
ters appear slimmer than they are wide. The default character expansion factor is 1.0. An error 
is generated if efac is less than .01 or greater than 10. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
30 EBTBUNDL ASF is BUNDLED. 

48 ECEXFOOR Expansion factor is out of range. 

4-5.6. character_spacing ^Ccharspacing^ 


Cerror character_spacing (spcratio) 

Cfloat spcratio; /* spacing ratio */ 

character_spacing sets the spacing between characters based on the height of the charac- 
ters. The amount of space between characters is obtained by multiplying the character height 
by spcratio. The default character spacing factor is 0.1. An error is generated if spcratio is less 
than .01 or greater than 10. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
30 EBTBUNDL ASF is BUNDLED. 

48 ECEXFOOR Expansion factor is out of range. 
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4-5. 7. character_height (Ccharheighty 

Cerror character _height (height) 

Cint height; /* height in VDC */ 

The character_height function determines the height of text in VDC coordinates. The height is 
defined as the distance from the top to the bottom of the character. 

Notice that changing the character height implicitly changes the character spacing. 

The default character height is 1000. This may result in huge characters if VDC Space is reset 
from its default range (0-32767). If the X and Y dimensions of VDC Space are different, the 
height is calculated on the basis of the range of the x-coordinate of VDC space. 

ERRORS: 


5 

ENOTOPOP 

CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC 

30 

EBTBUNDL 

ASF is BUNDLED. 

49 

ECHHTLEZ 

Character height is less than or equal to zero. 

4.5.8. 

f ixed_f ont 

(C fixed font^ 


Cerror fixed_font (index) 

Cint index; /* fixed or variable width characters */ 

fixed_font is a nonstandard CGI function which allows characters to be of fixed or variable 
size. If index is nonzero, the characters are of uniform size, otherwise the characters are packed 
proportional to their actual sizes. If the character precision is STRING, this function has no 
effect. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
4-5.9. text_color (Ctextcolor^ 


Cerror text_co lor (index) 

Cint index; /* color */ 


text_color resets the color of the text, index selects an entry in the color lookup table. The 
default value of index is 1. An error is detected if index is not between 0 and 255. 


ERRORS: 

5 ENOTOPOP 
30 EBTBUNDL 
35 ECINDXLZ 


CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
ASF is BUNDLED. 

Color index is less than zero. 
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36 EBADCOLX Color index is invalid. 

4-5.10. char acter_or ientat ion ^Ccharorientationy 


Cerror character_or ientation (xup # yup , xbas© , ybase) 

C float xup, yup , xbas© ,ybas©; /* character base and character up vectors 

character_oriervtation specifies the skew and direction of text. The left side of the char- 
acter box lies on an invisible line called the character up vector whose slope is determined by 
xbase and xup. The bottom of the character box lies on an invisible line called the character 
base vector whose slope is determined by ybase and yup. 

If the character up vector and the character base vector are not orthogonal, the text is distorted. 
Calls to character_orientation have no effect if text precision is set to STRING. The 
default values for the character up vector and the character base vector are xup =1.0, yup =1.0, 
xbase = 0.0, and ybase = 0.0. 

The character up vector and the character base vector influence the character path and the char- 
acter alignment. For example, if xbase =—1.0 and the character path is RIGHT, the text is written 
to the left. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 

50 ECHRUPVZ Length of character up vector or character base vector is zero. 

4-5.11. character_path ^Ccharpath^ 


Cerror character _path (path) 

Cpathtype path; /* text direction */ 

The character_path function respecifies direction that text is written. The four possible direc- 
tions are RIGHT, LEFT, UP, and DOWN. The actual effect of character^path depends on the char- 
acter up vector and the character base vector. RIGHT specifies that the text is written in the 
direction of the character base vector . For example, if the direction of the character base vector 
points left instead of right (xup =— 1.0 instead of 1.0), the text will be written right-to-left instead of 
left-to-right which is the usual interpretation of RIGHT. LEFT specifies that the text is written in 
the opposite direction of the character base vector. The character up vector and character base 
vector essentially change functions when the character direction is set to UP or DOWN. UP 
specifies that the text is written in the direction of the character up vector. DOWN specifies that 
the text is written in the opposite direction of the character up vector. The default character 
path is RIGHT. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
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4.5.12. text_al ignment (Ctextalign,/ 


Cer r or text_a 1 ignment (ha lign, valign, hca 1 ind , vca 1 ind) 

Chaligntyp© halign; /* horizontal alignment type */ 

Cvaligntype valign; /* vertical alignment type */ 

Cfloat heal ind , veal ind ; /* continuous alignment indicators */ 

text_al ignment determines where the text is positioned relative to the starting point 
specified by the cl argument of the text or vdm_text function. The value of the halign 
argument (which must be one of LFT, CNTER, RGHT, NRMAL, CNT) determines where the charac- 
ter is placed in relation to the x component of the starting coordinate of the text position 
(specified by the cl argument of text). If the value of halign is LFT, the horizontal position of the 
text will begin at the left edge of the box enclosing the text. Similarly, if the value of halign is 
RGHT, the horizontal position of the text will begin at the right edge of the box enclosing the 
text. If the value of halign is CTR the horizontal position of the text will begin equidistant from 
the right and the left edges of the text box. NRML assigns the alignment based on the value of 
the character path (see Table 4-4). If the value of halign is CNT (continuous) the horizontal posi- 
tion of the text is determined by the argument healind. In this case, the text will begin healtnd 
percent of the width of the text box from the left edge of the character box. The default value 
of halign is NRML. 

The value of the valign argument (which must be one of TOP, CAP, HALF, BASE, BOTTOM, NOR- 
MAL, CONT) specifies where the character is placed in relation to the y component of the text 
position. If the value of valign is TOP, the vertical position of the text will begin at the top edge 
of the character box. If the value of valign is CAP, the vertical position of the text will begin at 
the cap line of the character. 14 Similarly, if the value of valign is BOTTOM, the vertical position 
of the text will begin at the bottom edge of the character box. If the value of valign is BASE, the 
vertical position of the text will begin at the baseline of the character. 15 If the value of valign is 
HALF the vertical position of the text will begin equidistant from the top and the bottom edges 
of the character box. NORMAL assigns the alignment based on the value of the character path 
(see Table 4-4). If the value of valign is assigned to CONT (continuous), the vertical position of 
the text is determined by the argument vcalind and will begin vealind percent of the distance 
from the bottom edge of the character box. The default value of valign is NORMAL. 


14 The cap line is defined as the invisible line corresponding to the top of the average character within a 
font. 

16 The baseline is defined as the invisible line corresponding to the bottom of the average character 
within a font. The baseline does not necessarily correspond to the bottom of a character. For example, a 
the tail of a lower-case g extends below the baseline. 
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Table 4-4: Normal Alignment Values 


Character 

Path 

Horizontal 

Normal 

Vertical 

Normal 

RIGHT 

LEFT 

BASELINE 

LEFT 

RIGHT 

BASELINE 

UP 

CENTER 

BASELINE 

DOWN 

CENTER 

TOP 


ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 

4.6. Color Attributes 

SunCGI supports only one color specification mode — INDEXED. Index color specification mode 
means that the red, green, and blue values (hereafter referred to as rgb values) are obtained from 
a table known as the color lookup table. The initial values of the color lookup table are provided 
in Table 4-5. If the device is black and white, nonzero color values are displayed as black; zero 
is displayed as white. 

Table 4-5: Default Color Lookup Table 


Index 

Color 

0 

black 

1 

red 

2 

yellow : 

3 

green 

4 

cyan 

5 

blue 

6 

magenta 

7 

white 


4.6.1. color_table (Ccotable) 


Cerror color_table (istart, clist) 

Cint istart; /* starting address */ 

Ccentry *clist; /* color triples and number of entries */ 

color_table resets color lookup table entries. The color lookup table is a set of 256 rgb 
entries. The argument istart determines the first entry in the color lookup table to be modified. 
The argument diet contains the color information for entry istart in terms of triples of values of 
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numbers ranging between 0 and 255. The last field of clist reports how many entries are 
modified. An error is generated if either the indices to the color lookup table are out of range. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 

35 ECINDXLZ Color index is less than zero. 

36 EBADCOLX Color index is invalid. 

4.7. Inquiry Functions 

The attribute inquiry functions permit examination of the current attributes. Attributes are 
reported in groups corresponding to the class of output primitive which they modify. The argu- 
ment to each inquiry function has its own structure type which has an element for each of the 
individual attributes (see Appendix D). 


4.7.1. inquire_line_attr ibutes (Cqlnattsj 

Clinatt *inquire_line_attributes () ; 

/* pointer to line attribute structure */ 

inquire_line_attributes reports the current line style, line width, line color, and 
polyline_bundle_index in the appropriate elements of the returned value of the function. 

typedef struct •( 

Cl intype style; 

Cfloat width; 

Cint color; 

Cint index; 

> Clinatt; 

Since inquire_line_attributes does not return an error, errors are only reported in 
INTERRUPT mode. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
4-7.2. inquire_marker_attr ibutes (Cqmkattsy 

Cmarkatt * inquire_marker_attr ibutes () ; 

/* pointer to marker attribute structure */ 

inquire_marker_attr ibutes reports the current marker style, marker width, marker color, 
and polymarker_bundle_index in the appropriate elements of the returned value of the 
function. 
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typed© f struct { 

Cmartyp© type; 

Cfloat size; 

Cint color; 

Cint index; 

} Cmarkatt; 

Since inquire_marker._att:ribut:es does not return an error, errors are only reported in 
INTERRUPT mode. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 

4.7. 3. inquire_f ill_area_attributes (Cqf lareaatts^ 

Cfillatt *inquire_fill_ar@a_attributes () ; 

/* pointer to fill area attribute structure */ 

The current interior style , perimeter visibility, fill color, hatch index, pattern index, fill area bun - 
die index, perimeter style , perimeter width, and perimeter color can be obtained by using the 
±nquire_fil l_attribut:es function. 

typed© f struct { 

Cintertype style; 

Cflagtype visible; 

Cint color; 

Cint hatch_index; 

Cint pattern_index; 

Cint index; 

Clintyp© pstyle; 

Cfloat pwidth; 

Cint pcolor; 

> fillatt; 

Since inquire_fill_area_attributes does not return an error, errors are only reported 
in INTERRUPT mode. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 

4 . 7.4 . inquire_pattern_attr ibutes fCqpatatts ) 


Cpatternatt *inquire_pattern_at tributes () ; 

/* pointer to pattern attribute structure */ 

±nquire_pattern_attributes reports the current pattern index , row count, column count, 
color list, pattern reference point, and pattern size. 
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typed© f struct { 

Cint cur_ind@x; 

Cint row; 

Cint column; 

Cint *colorlist; 

Ccoor *point; 

Cint dx; 

Cint dy; 

} patternatt; 

Since inquire__pattern_attributes does not return an error, errors are only reported in 
INTERRUPT mode. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
4.7.5. inquire_text_attributes fCqtextatts,/ 


Ctextatt *inquire_text_attributes () ; 

/* pointer to text attribute structure */ 

inquire_text_attributes reports the current font set , text bundle index , font , text preci- 
sion, character expansion factor , character spacing, text color , character height, character base 
vector , character up vector , character path , and text alignment. 

typedef struct { 

Cint fontset; 

Cint index; 

Cint current__font ; 

Cprectype precision; 

C float exp_f actor ; 

C float space; 

Cint color; 

Cint height; 

Cfloat basex; 

Cfloat basey; 

Cfloat upx; 

Cfloat upy; 

Cpathtype path; 

Chaligntype halign; 

Cvaligntype valign; 

Cfloat hcalind; 

Cfloat vcalind; 

} textatt; 

Since inquire_text_attributes does not return an error, errors are only reported in 
INTERRUPT mode. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
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4-7.6. inquire_aspect_source_ flags (Cqasfs) 


Cflaglist *inquire_aspect_source_f lags () 

/* pointer to text attribute structure */ 

inquire_aspect_source_ flags reports whether attributes are set individually by returning 
all of the values of the ASFs. The element n of the flaglist struct is set to 18. The definitions of 
each flag are in Table 4-2. 

typedef struct { 

Cint n; 

Cint *num; 

Casptype * value; 

} Cflaglist; 

Since inquire_aspect_source_ flags does not return an error, errors are only reported in 
INTERRUPT mode. 

ERRORS: 

5 ENOTOPOP 

CGI not in proper state CGI shall be in state VDOP, VSOP, or VSAC. 
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CGI describes an input device as consisting of a measure and a list of associations with triggers. 
A trigger corresponds to a physical input device such as a mouse button. A measure reports the 
current value of the device such as x,y position for a locator device. SunCGI input functions 
apply to all classes of input devices. The classes of devices that are offered are listed in Table 5- 
1 . 


Table 5-1: Devices Offered by SunCGI 


Device Class Max. Number 

Description 

IC.CHOICE 

3 

Mouse button (trigger) 17 

ICJLOCATOR 

4 

x, y position 

ICLSTRING 

1 

Keyboard input 

IC_STROKE 

3 

Array of x, y positions 

IC_VALUAT OR 

4 

Normalized x position 


When a trigger is activated, the measure of the device is reported to the application program by 
use of the event functions. 

The effect of the event functions depends on the state of the input device (see Table 5-2). Before 
an input device is initialized it is in the RELEASED state. When an input device is first initial- 
ized, it is in the NO_EVENTS state. 

The measure (value) of the input device is the device-dependent information that the application 
program wants (for example, the LOCATOR returns the x,y position of the cursor. The measure 
of an input device in the NOJSVENTS state is the measure that it was initialized with. The meas- 
ure of an input device in the NO_EVENTS state does not change with activation of a trigger. For 
example, the measure of a LOCATOR does not change when the mouse moves. 

The measure of an input device is changed by trigger activation when the input device is in 
either the REQUEST_EVENT, RESPOND_EVENT or QUEUE_EVENT state. If the input device is in 
the REQUEST_EVENT state its measure is set by the first trigger activation after the 
initiate_request function is called. If the input device is in the RESPOND_EVENT state its 


17 The left mouse button is choice 2, the middle button is choice 3, and so on. 
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measure is set by the most recent trigger activation. Previous trigger activations are not stored. 
When an input device is in the QUEUEJSVENT state, trigger activation is buffered by the event 
queue. The event queue processes inputs in the order that they are received provided that the 
event queue is not overflowing. 


Table 5-2: States of Input Devices 


State 

Brief Description 

RELEASED 

Device not initialized. 

NO_EVENTS 

Device initialized, but unable to process events. 

REQUEST JCVENT 

Device measure set by first (and only first) trigger activation. 

RESPOND_EVENT 

Device measure settable by most recent trigger activation. 

QUEUE JEVENT 

Device able to post events on the event queue. Device measure 
settable by trigger activation when processed. 


The figure below illustrates the CGI input state model. 


Get Last Req. Input 
Await Event 



1 1 

1 0 

J request ! 

' event • 
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! respond J 

' event ■ 
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! queue | 

» event • 
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0 8 

I I 

l -t f- J 

8 8 

1 I 

,~ T - — "f" J 

Sample Input 

Init Request 
(Request Input, 

Enable Events cause error) 

Sample Input 
(Init Request 

Request, 

Enable Events cause error) 

trigger fires 
Sample Input 
Await Event 
(request, 

init request cause error) 


Figure 5-1: CGI Input State Model 
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In addition to reporting input to an application program, you may want to have the measure of a 
device displayed on all active view surfaces (called tracking). Tracking must be explicitly 
enabled for each device. In addition, the type of track is selectable for some input devices. 


5.1. Input Device Management 

Before input can be processed, the individual input devices must be initialized and associated 
with triggers. Input device initialization requires that at least one view surface is active. Typi- 
cally, the procedure for initializing an input device includes calls to the initialize_lid, 
enable_e vents, and associate functions which turn on an input device and permit it to 
receive input from an associated trigger (see the following example). 

{ /* initialize LOCATOR input device. get input, and close */ 

Cinrep ival; 

Clogical stat; 

Cint trig; 

ival.xypt.x = 16384; /* put cursor in the middle of the view surface */ 
ival.xypt.y = 16384; 

initialize_lid(IC_LOCATOR. l.&ival) ; 

associate (2, IC_LOCATOR, 1) ; /* associate locator with mouse button 1 */ 

request_input (IC_LOCATOR, 1, 5000000, fistat , fiival , &trig) ; /* wait five seconds */ 
if (stat == TRUE) 

print f (" trigger activated at %d %d \n" , ival . xypt .x, ival . xypt .y) ; 

else 

printf(" trigger not activated \n") ; 
disable_events (IC_L0CAT0R, 1) ; /* shut device off */ 
dissociate (2 , IC_L0CAT0R, 1) ; 
release_input_device (IC_L0CAT0R, 1) ; 

> 


5.1.1. initialize_lid (Ginitlid^ 


Cerror initialize_lid (devclass, devnum, ival) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

Cinrep 4 ival; /* initial value of device measure */ 

initialize_lid (lid — Logical Input Device) must be called for an input device before it can 
be referenced by any other input function, initializejlid changes the state of the specified input 
device from RELEA SED to N0_EVENTS. The argument devclass specifies one of the supported dev- 
ices, and devnum indicates the number of the device within that class. The argument ival sets 
the initial measure of the device. The structure Cinrep contains different elements for each 
type of measure. An error is generated if the device does not exist, if it is already initialized, or 
if the initial value is out of range. You must set the appropriate field of ival, or an error will 
be generated. 
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typed© f struct { 

Ccoor *xypt; 
Ccoorlist ^points; 
Cfloat val; 

Cint choice; 

Cchar * string; 

} C inrep; 


/* LOCATOR */ 

/* STROKE devices */ 
/* VALUATOR device */ 
/* CHOICE devices */ 
/* STRING device */ 


Notice that whenever a device is initialized, no associations with triggers are made. This must 
be done by having your application program call the appropriate functions. 


ERRORS: 


4 

ENOTVSAC 

CGI not in proper state: CGI shall be in state VSAC. 

80 

EINDNOEX 

Input device does not exist. 

82 

EINDALIN 

Input device already initialized. 18 

95 

EBADDATA 

Contents of input data record are invalid. 

96 

ESTRSIZE 

Length of initial string is greater than the implementation defined max- 


imum. 


5. 1.2. release_input_device ^Crelidevj 

Cerror release_input_device (devclass , devnum) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

release_input_device releases all associations with triggers, and removes all pending events 
from the device from the event queue . release_input_device changes the state of the 
specified input device from NOJ5VENTS to RELEASED. An error is produced if devclass , devnum 
does not refer to an existing or initialized device. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

80 EINDNOEX Input device does not exist. 

81 EINDINIT Input device not initialized. 

5.1.5. f lush_event_queue fCf lusheventquj 

Cerror f lush__event_queue () 

f lush_event;_queue discards all events in the event queue. The purpose of flush_event_queue 
is to return the event queue to a stable state (NO_OFLO). This function should be used 

18 The ANSI standard allows initialized input devices to be re-initialized. SunCGI does not because it is 
felt that re-initialization is usually a mistake. 
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carefully to avoid throwing away mouse-ahead or type-ahead inputs. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in either in state VDOP, VSOP, 
or VSAC. 


5.1.4. select ive_flush_of_event_queue (Cselectf lusheventqu) 

Cerror selective_f lush_of_event_queue (devclass, devnum) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

s©lective_f lush_of_event_queue discards all events in the event queue which are gen- 
erated by the specified device. selective_f lush_of_event_queue does not affect the 
state of the specified input device, devclass, devnum must refer to an existing or initialized dev- 
ice or an error is produced. However, no error is returned if no events from the specified device 
are pending. 

ERRORS: 

5 ENOTOPOP CGI not in proper state CGI shall be in either in state VDOP, VSOP, 
or VSAC. 

80 EINDNOEX Input device does not exist. 

81 EINDINIT Input device not initialized. 

5.1.5. associate (Cassoc^ 

Cerror associate (trigger , devclass, devnum) 

Cint trigger; /* trigger number */ 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

The function associate links a trigger to a specific device. The trigger numbers are listed in 
Table 5-3. 


Table 5-3: Triggers Offered by SunCGI 


Trigger 

Number 

Keyboard 

1 

Mouse Button No. 1 

2 

Mouse Button No. 2 

3 

Mouse Button No. 3 

4 

Mouse Position 

5 


Multiple associations are allowed; however, some associations are not allowed (for example, 
ICLLOCATOR may not be associated with the keyboard). The interaction between an IC_STROKE 
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device and the trigger requires some explanation. IC_STROKE can only be linked with the mouse 
buttons. IC_STROKE returns an array of coordinates in VDC space. The first coordinate is 
entered when the mouse button is initially depressed, the last coordinate is entered when the 
mouse button is released. For IC_LOCATOR and IC_VALUATOR devices, the measure is reported 
when the mouse button is depressed. 

ERRORS: 


4 

ENOTVSAC 

CGI not in proper state: CGI shall be in state VSAC. 

80 

EINDNOEX 

Input device does not exist. 

81 

EINDINIT 

Input device not initialized. 

83 

EINASAEX 

Association already exists. 

84 

EINAI IMP 

Association is impossible. 

86 

EINTRNEX 

Trigger does not exist. 

5.1.6. 

set_default_trigger__associations ^Csdefatrigassoc^ 

Cerror set_default__trigger ..associations (devclass, devnum) 
Cdevoff devclass; /* device type */ 


Cint devnum; /* device number */ 

The function set_default_trigger_associations links a trigger to a specific device. The rules for 
trigger association are the same as those for the associate function. The default associations are 
listed in Table 5-4. 


Table 5-4: Default Trigger Associations 


Device Class 

Default Trigger 

ICLLOCATOR 

5 

IC_VALUATOR 

3 

ICLSTROKE 

4 

ICLCHOICE 

2 

ICJSTRING 

1 


ERRORS: 


4 

ENOTVSAC 

CGI not in proper state: CGI shall be in state VSAC. 

80 

EINDNOEX 

Input device does not exist. 

81 

EINDINIT 

Input device not initialized. 

83 

EINASAEX 

Association already exists. 

86 

EINTRNEX 

Trigger does not exist. 
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5.1.7. dissociate ^Cdissocj 

Cerror dissociate (trigger , devclass, devnum) 

Cint trigger; /* trigger number */ 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

The function dissociate removes the association between a trigger and the specified device. If 
the dissociate function is called while there are events pending on the event queue , the pending 
events are discarded. 

ERRORS: 


4 

ENOTVSAC 

CGI not in proper state: CGI shall be in state VSAC. 

80 

EINDNOEX 

Input device does not exist. 

81 

EINDINIT 

Input device not initialized. 

85 

EINNTASD 

association does not exist. 

86 

EINTRNEX 

Trigger does not exist. 

5.1.8. 

set_initial 

..value fCsinitvalj 


Cerror set_initial_valu© (devclass, devnum, value) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

Cinrep * value; /* device value */ 

set_initial_value sets the current measure of the specified device. This function resets the 
position of the track, if the track is appropriate and activated. set_initial_valu© also 
resets the request register. 

ERRORS: 


4 

ENOTVSAC 

CGI not in proper state: CGI shall be in state VSAC. 

80 

EINDNOEX 

Input device does not exist. 

81 

EINDINIT 

Input device not initialized. 

95 

EBADDATA 

Contents of input data record are invalid. 

96 

ESTRSIZE 

Length of initial string is greater than the implementation defined max- 
imum. 


5.1.9. set_valuator_range /tsvalrangej 


Cerror set_valuator_range (devnum, min, max) 
Cint devnum; /* device number */ 

Cfloat min, max; /* limits of valuator */ 
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set_valuator_range specifies the limits of the valuator. Device coordinates are mapped into 
the valuator range. All valuator events which are on the event queue are not rescaled. You 
must dequeue these events either with the selective_f lush_o f_evervt_queue function or 
f lush_event_queua. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

80 EINDNOEX Input device does not exist. 

81 EINDINIT Input device not initialized. 

5.2. Tracking 

Tracking functions determine how the measure of an input device is displayed on the view sur- 
face. Each class of devices has its own set of possible tracks (given in Table 5-4). Although 
SunCGI allows certain classes of devices to track simultaneously, all types of input devices are 
not allowed to track at once. Tracking is not provided in the NO_EVENTS state unless the track 
type is PRINTERS_FIST. 


Table 5-5: Available Track Types 


Trigger 

Number 

Track Type 

ICLCHOICE 

1 . 

PRINTERS J'IST 

IC_LOCATOR 

1 . 

PRINTERSJ1ST 

ICJ3TRING 

1 . 

PRINTERSJFIST 


2. 

STRINGJTRACK 

ICLSTROKE 

1 . 

PRINTERSJFIST 


2. 

SOLID .LINE 


3. 

X_LINE 


4. 

Y_LINE 


5. 

RUBBERJBAND_BOX 

ICLVALUATOR 

1 . 

PRINTERSJFIST 


2. 

STRINGJTRACK 


5.2.1. track_on (Ctrackon^ 
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Cerror track_on (devclass, devnum, tracktype, trackregion, value) 

Cdevoff devclass; /* device type ‘ / 

Cint devnum; /* device number */ 

Cint tracktype; /* track number */ 

Ccoorpair ‘trackregion /* window where track is enabled */ 

Cinrep ‘value; /* device value */ 

track_on initiates track (or echo) for a specific device. The tracktype argument specifies the 
type of track to be used. See table 5-5. The trackregion argument specifies a rectangular subre- 
gion of the view surface (in VDC Space) where tracking is active. The returned argument value 
reports the device measure at the time track_on is called. The track is initially displayed on the 
first view surface opened. 

The xypt element of value must be set to initially position the cursor. The reference point for 
ICLSTROKE echos 2 through 5 is the first point in the stroke array. The reference point for 
STRIN G_TRACK echo is the append_text concatenation point, and can be changed by calling 
text or append_text. The trackregion argument is not used and the device tracks in all 
areas of the view surface. 

ERRORS: 


4 

ENOTVSAC 

CGI not in proper state: CGI shall be in state VSAC. 

88 

EINECHON 

Track already on. 

91 

EINETNSU 

Track type not supported. 

95 

EBADDATA 

Contents of input data record are invalid. 

96 

ESTRSIZE 

Length of initial string is greater than the implementation defined max- 


imum. 


5 . 2 . 2 . track_off (Ctrackof fj 


Cerror track_off (devclass , devnum, tracktype, action) 
Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

Cint tracktype; 

Cint action; 


The function track_off terminates tracking for the specified input device. However, the printer’s 
fist track always remains. For this reason, the tracktype and the action arguments are always 
ignored. 


ERRORS: 

4 ENOTVSAC 

80 EINDNOEX 

81 EINDINIT 


CGI not in proper state: CGI shall be in state VSAC. 
Input device does not exist. 

Input device not initialized. 
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5.3. Event Functions 

Event functions allow the application program to set and obtain the current measure of input 
devices and triggers. No device-specific input routines exist in SimCGI. Therefore, each of the 
following functions requires explicit identification of an input device. There are two input 
buffers: the event queue and the request register. The event queue is a FIFO (First In, First Out) 
buffer containing input events which are not generated by the request functions. The request 
register is a one-element per device buffer which contains the measure caused by the last input 
event, if the device has been put in request^event mode. 

5 . 3 . 1 . s amp le_ input fCsampinpj 

Cerror sample.. input (devclass , devnum, valid, sample) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

Clogical *valid; /* device status */ 

Cinrep * sample; /* device value */ 

sample_input reports the current measure of the specified input device in the returned argu- 
ment sample. The returned argument valid reports whether the device is initialized and 
prepared to receive an input. The current measure of the device may be set by a queued event, 
a requested event, or a device initialization depending on the state of the input device and the 
most recent trigger activation(s). See the chapter introduction for an explanation of the relation- 
ship between the measure of an input device and the state of an input device. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

80 EINDNOEX Input device does not exist. 

81 EINDINIT Input device not initialized. 

5 . 3 . 2 . initiate_request fCinitreqj 

Cerror initiate_request (devclass, devnum) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

initiate_request sets up a device so that the measure resulting from the next trigger 
activation will be placed in the request register. initiate_request puts the device in the 
REQUEST_EVENT state. The value caused by the trigger activation can be obtained by the 
get_last_ requested_input function. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

80 EINDNOEX Input device does not exist. 

81 EINDINIT Input device not initialized. 
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85 EINNTASD No triggers associated with device. 

5 . 3 . 8 . request_input ^Creqinp^ 

Cerror request_input (devclass, devnurn, timeout, valid, sample, trigger) 
Cdevoff devclass; /* device type */ 

Cint devnurn; /* device number */ 

Cint timeout; /* amount of time to wait for input */ 

Cawresult ‘valid; /* device status */ 

Cinrep ‘sample; /* device value */ 

Cint ‘trigger /* trigger number */ 

request_input awaits activation of a trigger associated with a specific device, for timeout 
microseconds, requestjnput puts the input device in the RESPONDJSVENT state. If a trigger is 
activated within this period, the activating trigger and the device measure are returned in the 
trigger and sample arguments respectively. If the trigger is not activated within this period, the 
current device measure is returned in the sample argument, trigger is set to zero. 

Cawresult is defined as an enumerated type as follows: 

typedef enum { 

VALID_DATA, 

TIMED_OUT, 

DISABLED, 

WRONG_STATE , 

NONSUPPORTED 
} Cawresult; 

valid is set to VALID JDATA if a trigger is activated within the specified timeout period and 
TIMED_OUT otherwise. If the device is not in the state RESPONDJSVENT, valid is set to DISABLED. 
If the device is not a legal device, valid is set to NOT_SUPPORTED. valid is set to WRONG_STATE 
if SunCGI is not in state VSAC. 

ERRORS: 


4 

ENOTVSAC 

CGI not in proper state: CGI shall be in state VSAC. 

80 

EINDNOEX 

Input device does not exist. 

81 

EINDINIT 

Input device not initialized. 

94 

EINEVNEN 

Events not enabled. 

99 

EINNTRSE 

Input device not in state RESPOND EVENTS. 


5.3.4. get_last_requested_input /'Cgetlastreqinpj 

Cerror get_last_requested_input (devclass, devnurn, valid, sample) 

Cdevoff * devclass; /* device class and number */ 

Cint ^devnurn; 

Clogical *valid; /* device status */ 

Cinrep ^sample; /* device value */ 

get_last_requested_input returns the contents of the request register. The returned 
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argument valid reports if the device exists and is initialized. The returned argument sample 
reports the latest event in the request register. If no event is in the request register, the initial 
device value is reported. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

80 EINDNOEX Input device does not exist. 

81 E INDINIT Input device not initialized. 

5 . 3 . 5 . enable_events /Ceneventsj 


Cerror enable_events (devclass , devnum) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

Calling enable_events allows the specified device to put events on the event queue. enable_events 
puts the input device in the QUEUE_EVENT state. An error is generated if the device specified by 
devclass, devnum does not exist or is not initialized. 

ERRORS: 


4 

ENOTVSAC 

CGI not in proper state: CGI shall be in state VSAC. 

80 

EINDNOEX 

Input device does not exist. 

81 

EINDINIT 

Input device not initialized. 

93 

EIAEVNEN 

Events already enabled. 


5 . 3 . 6 . disable_events fCdaeventsJ 

Cerror disable_events (devclass , devnum) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

disable_events prevents the specified device from putting events on the event queue or mak- 
ing new associations with triggers. disable_events puts the input device in the NO_EVENT 
state. However, existing entries on the event queue are not removed and existing associations 
remain, devclass, devnum must refer to an existing or initialized device or an error is produced. 

ERRORS: 


4 

ENOTVSAC 

CGI not in proper state: CGI shall be in state VSAC. 

80 

EINDNOEX 

Input device does not exist. 

81 

EINDINIT 

Input device not initialized. 

94 

EINEVNEN 

Events not enabled. 
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5.3.7 . await_event fCawaitevj 

Cerror await_event (timeout , valid, devclass, devnum, 

measure, m©ssage_link, replost, t±me_ stamp, qstat, overflow) 

Cint timeout; /* amount of time to wait for input */ 

Cawresult *valid; / A status */ 

Cdevoff * devclass; /* device type */ 

Cint *devnum; /* device number */ 

Cinrep ^measure; /* device value */ 

Cmesstype & message_link; /* type of message */ 

Cint *replost; /* reports lost */ 

Cint *time_stamp; /* time__stamp */ 

Cqtype * qstat; /* queue status */ 

Ceqflow * over flow; /* event queue */ 

await.event processes the event at the head of the event queue. If the event queue is EMPTY, 
then await_event waits for timeout microseconds for a trigger to be activated, valid is set to 
VALIDJ)ATA if a trigger is activated within the specified timeout period and TIMED_OUT other- 
wise. valid is set to WRONG.STATE if SunCGI is not in state VSAC. 

If either the event queue is not empty or a trigger is activated, the class, the number, and the 
value of the device generating the event are reported in the returned arguments devclass , dev- 
num, and measure. If timeout is less than 0, SunCGI waits until a trigger is activated. If two 
events on the event queue have the same trigger but different values, the argument, messagejlink 
is assigned to SIMULTANEOUSJ3VENT_FOLLOWS; otherwise the argument messagejlink is set to 
SINGLE J^VENT. 

The replost and time_stamp arguments should be ignored and are always zero. The returned 
argument qstat reports the queue status after the event is removed from the head of the event 
queue. 


typedef enum { 

N0T_VALID, EMPTY, NON-EMPTY, ALMOST_FULL, FULL 
> Cqtype; 

Qstat is set to EMPTY if the event queue has no pending events. Qstat is set to N0N_EMPTY if 
the event queue has events pending, but is not FULL or ALMOSTJTJLL. Qstat is set to 
ALMOSTJTJLL if there is room for only one more event on the event queue. Qstat is set to FULL 
if there is no room for more events on the event queue. The argument overflow can assume one 
of two values: NO_OFLO, or OFLO. 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

97 EINQOVFL Input queue has overflowed. 

5.4. Status Inquiries 

The current state of the input devices, triggers, and the event queue can be obtained by using 
the functions discussed in this section. 
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5.4.1. inquire_lid_state_list /'Cqlidstatelisj 

Cerror inquir©_lid_state_list (devclass, devnum, valid, list) 

Cdevoff devclass; 

Cint devnum; /* device type, device number */ 

Clogical *valid; /* device supported at all */ 

Cstatelist *list; /* table of descriptors */ 

inquire_lid_state_list reports the status of a specific input_ device specified by devclass 
and devnum. The argument valid reports whether the device is supported at all. The list argu- 
ment reports the track, associations, state, and measure of the device in the appropriate ele- 
ments of list. When checking the elements of list, first check the state element — if state is 
RELEASE, the other elements of list are undefined. 

typed© f struct { 

Clidstate state; 

Cpromstate prompt; 

Cackstate acknowledgement; 

Cinrep * current; 

Cint n; 

Cint * triggers; 

Cechotype echotyp; 

Cechostate echosta; 

Cint echodat; 

} Cstatelist; 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

80 EINDNOEX Input device does not exist. 

5.4-2- inquire__lid_state fCqlidstatej 

Cerror inquire_lid_state (devclass, devnum, valid, state) 

Cdevoff devclass; 

Cint devnum; /* device type, device number */ 

Clogical *valid; /* device supported at all */ 

Clidstate *state; /* table of descriptors */ 

inquire_lid_state reports the status of a specific input device specified by devclass and dev- 
num. The argument valid reports whether the device is supported at all. The state argument 
(of type Clidstate) reports the current state of the specified input device. 

typed© f enum { 

RELEASE, NO_EVENTS, REQUESTJEVENT, RESPONDJEVENT, QUEUE_EVENT 
} Clidstate; 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 
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80 EINDNOEX Input device does not exist. 

5 . 4 -S. inquire_trigger_state fCqtr igstatej 

Cerror inquire_trigger_state (trigger , valid, list) 

Cint trigger /* trigger number */ 

Clogical ‘valid; /* trigger state */ 

Ctrigstate *list; /* trigger description table */ 

inquire_trigger_state describes the binding between a trigger and an input device. If the 
state element of the returned argument list is INACTIVE, no associations have been made with the 
trigger. An error is generated if the trigger does not exist. 

typed© f struct { 

Cactstate state; /* state */ 

Cassoclid *assoc; /* list of associations */ 

} Ctrigstate; 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 

86 EINTRNEX Trigger does not exist. 

5.4.4. inquire_event_queue_state fCqevquestatej 

Cerror inquire_event_queue_state (qstat , qflow) 

Cqtype * qstat; /* queue state */ 

Ceqflow * qflow; /* overflow indicator */ 

inquire_event_queue_state reports the status of the event queue. Qstat indicates whether 
any events are pending. The argument qflow reports if the event queue is overflowing. 

typedef enum { 

NOT_VALID, EMPTY, NON-EMPTY, ALMOST_FULL , FULL 
> Cqtype; 

typedef enum { 

NO_OFLO, OFLO 
} Ceqflow; 

ERRORS: 

4 ENOTVSAC CGI not in proper state: CGI shall be in state VSAC. 


Revision A of 15 May 1985 


5-15 






Appendix A 


Differences between SunCore and SunCGI 


This appendix provides an introduction to SunCGI for programmers who have programming 
experience with SunCore or graphics packages based on the ACM Core Graphics Specification. 
The three major differences between SunCore and SunCGI are in the areas of output primi- 
tives, segmentation, and input. While SunCore is generally a ‘higher-level’ package, SunCGI 
has capabilities which are not available in SunCore. 


A.l. Output Primitives 

The major differences in drawing objects to the screen between SunCore and SunCGI are that 

1. SunCGI does not support three-dimensional primitives, and 

2. SunCGI does not have floating-point world coordinates or image transforms, and, 

3. SunCGI does not support the concept of current position, and 

4. SunCGI does not support textured color lookup table for black-and-white devices. 

However, SunCGI provides a wider variety of geometrical and raster primitives, and more con- 
trol over the drawing of text. These differences are summarized in Table A-l. 

Table A-l: Difference in Output Primitives 


Feature 

SunCore 

SunCGI 

Three-Dimensional Output Primitives 

YES 

NO 

Current Position 

YES 

NO 

Textured Color Lookup Tables 

YES 

NO 

Polygons with Invisible Edges 

NO 

YES 

Circles and Ellipses 

NO 

YES 

Cell Arrays 

NO 

YES 

Character Clipping 

NO 

YES 
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A.1.1. Output Aspects of SunCore not Supported by SunCGI 

SunCGI does not support three-dimensional output primitives, current position, or textured 
color lookup tables for black-and-white devices. Since three-dimensional output primitives are 
not supported, no shading or lighting functions are provided either. Furthermore, no rotation or 
translation functions are provided. Therefore, if you want to rotate a geometrical output primi- 
tive, these operations must be done by your application program. 

Since SunCGI does not maintain the current position of the output ‘cursor’, relative drawing 
functions such as polygon_rei_8 are not supported. However, the application programmer can 
implement this function by specifying all coordinates as a base register plus a constant. The base 
register can be used by the application program to maintain the value of the current position. 

For black-and-white devices, SunCore interprets the entries in the color lookup table with 
indices greater than one as patterns. SunCGI interprets all color lookup table entries greater 
than zero as black. Patterns in SunCGI are explicitly specified in the pattern table and invoked 
by using the PATTERN or HATCH interior styles. In addition, while patterns in SunCore are all 
four-by-four matrices, patterns in SunCGI have variable dimensions. 

A.1.2. Output Features of SunCGI not Available in SunCore 

SunCGI offers geometrical and raster primitives not available in SunCore, as well as increased 
control over the drawing of text. SunCGI provides circles and ellipses. SunCGI also supports 
the cell array which is a raster array whose element size is a function of the screen size. 
SunCGI clips characters in parts if the text precision is set to STROKE. 


A.2., Segmentation 

SunCGI does not support segmentation. This effect influences the effect of attribute calls. In 
SunCore, some attributes (for example, highlighting) apply to entire segments. Since no con- 
cept of segmentation exists in SunCGI, these attributes are not offered. Furthermore, SunCGI 
does not allow the saving or restoring of segments to the screen, so screen repainting functions 
must be completely defined by the application program, unless the view surface is initialized as a 
retained view surface and is not resized. 


Ao3„ Differences in Input Functions between SunCore and SunCGI 

SunCore provides device-specific functions for setting input device parameters and reading 
input from them. SunCGI provides no device dependent calls. SunCGI has three methods for 
obtaining the measure of input devices 

1. by first activation (REQUEST EVENT), 

2. by most recent activation (RESPOND EVENT), or 

3. by mediating input requests through the event queue (QUEUE EVENT). 

Furthermore, SunCGI allows the explicit binding of triggers (physical input devices) to logical 
input devices. 
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SunCGI does not support certain optional aspects of the proposed draft ANSI CGI standard. 
Most notably SunCGX does not support the full constellation of negotiation functions or track- 
ing. SunCGX does not allow the resetting of coordinate type , coordinate precision , or color 
specification mode because to do so would greatly reduce the speed of application programs writ- 
ten in SimCGI. Furthermore, SunCGI does not support echoing functions for input, but pro- 
vides the tracking functions instead. 

Unsupported Control Functions 

vdc_typ@ 

vdc_precision_for__ Integer _points 

vdc_precision_for_real_points 

integer_precis ion 

real_precision 

index_precision 

color_sel©ction_mode 

color__precision 

color_index_precision 

viewport_specif ication_xnoda 

make_picture_current 

Unsupported Input Functions 

set_prompt_state 

set__acknowledgement_state 

echo_on 

echo_of f 

echo_update 

The following SunCGI functions are nonstandard (that is, are not in the standards document) 
and are included to make CGI easier to use. In addition, SunCGI has non-standard view surface 
arguments for certain control functions. 

Non Standard Control Functions 

open_cgi 

open_vws 

act ivate_vws 

deact ivat e_vws 

close.vws 

close_cgi 

Non Standard Attribute Functions 


Revision A of 15 May 1985 


B-l 



Unsupported Aspects of CGI 


SunCGI Reference Manual 


d© f ine_bund le_index 
1 ine_endsty 1© 
f ixed_font 

set_global_drawing_mode 
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This appendix lists the types used by SunCGI functions. The definition of these types can be 
found in <cgitypes .h>. These definitions are listed here in alphabetical order to make the 
manual easier to read. 

typed© f enum { 

ACK_ON , ACK_OFF 
} Cackstate; 

typed© f enum { 

ACTIVE, INACTIVE 
} Cact state; 

typed© f enum { 

CLEAR, NO_OP , RETAIN 
} Cacttype; 

typed© f enum { 

INDIVIDUAL, BUNDLED 
} Casptype; 

typed© f struct { 

Cint n; 

Cdevoff * class; 

Cint ♦assoc; 

} Cassoclid; 

typed© f enum { 

CALID_DATA, 

TIMED_OUT, 

DISABLED, 

WRONG_STATE, 

NONSUPPORTED 
} Cawresult; 
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typed© f enum { 

BITTRUE, BITNOT 
} Cbitmaptype; 

typed© f enum { 

TRANSPARENT, OPAQUE 
} Cbmode; 

typed© f struct { 

Cl intype line_type; 

C f 1 o at 1 ine_wi dth ; 

Cint line_color; 

Cmartype marker _type; 

C float marker_size; 

Cint marker _color; 

Cintertype inter ior_style; 

Cint hatch__index; 

Cint pattern_index ; 

Cint fill_color; 

Cl intype perimeter_type; 

C f 1 oat per imet er_width ; 

Cint perimeter_color ; 

Cint text_font; 

Cprectype text_precision; 

Cfloat character_expansion; 

C float character_spacing; 

Cint text_color; 

} Cbunatt; 

typedef struct { 

unsigned char *ra; 
unsigned char *ga; 
unsigned char *ba; 

Cint n; 

y Ccentry; 

typedef enum { 

OPEN, CLOSE 
} Ccflag; 
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typed© f struct { 

Cint numloc; 

Cint numval ; 

Cint numstrk; 

Cint numchoica; 

Cint numstr; 

Cint numtrig; 

Csuptyp© ©vent_queue; 

Csuptyp© asynch; 

Csuptyp© coord_map; 

Csuptyp© echo; 

Csuptyp© tracking; 

Csuptyp© prompt; 

Csuptyp© acknowledgement; 
Csuptyp© trigger_manipulation; 
} Ccgidesctab; 

typed© f enum { 

YES, NO 
} Cchangetype; 

typed© f char Cchar ; 

typed© f enum { 

CLIP, 

NOCLIP, 

CLIP__RECTANGLE 

> Cclip; 

typed© f enum { 

CHORD, PIE 
} Cclosetype; 

typed© f enum { 

REPLACE, AND, OR, NOT, XOR 
} Ccombtype; 

typed© f struct { 

Cint x; 

Cint y; 

} Ccoor; 

typed© f struct { 

Ccoor *ptlist; 

Cint n; 

} Ccoor list; 
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typed© f struct { 
Ccoor * upper; 
Ccoor * lower; 
} Ccoorpair; 


typedef enum { 

IC_LOCATOR, 
IC_STROKE , 
IC_VALUATOR, 
IC_CHOICE , 
ICJSTRING, 
IC_PICK 
} Cdevoff; 


typedef enum { 

E_TRACK , 

E__ECHO, 

E_TRACK_OR_ECHO , 
E_TRACK_AND_ECHO 
} Cechoav; 

typedef struct { 

Cinrep ft echos; 

Cint n; 

} Cechodatalst ; 


typedef enum { 

ECHO_OFF, ECHO_ON , TRACK_ON 
} Cechostate; 


typedef struct { 

Cechostate * echos; 
Cint n; 

} Cechostatelst ; 


typedef enum { 

PRINTERS_FIST, NO_ECHO, HIGHLIGHT, RUBBER_BAND_BOX , 

DOTTED_LINE, SOLID_LINE, STRING_ECHO, XLINE, YLINE 
} Cechotype; 


typedef struct { 

Cint n; 

Cechoav * elements; 
Cechotype * echos ; 

} Cechotype 1st; 


typedef enum { 

NATURAL, POINT, BEST_FIT 
> Cendstyle; 
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typed© f enum { 

NO_OFLO, OFLO 
} Ceqflow; 

typedef Cint Cerror; 

typed© f enum { 

INTERRUPT, NO.ACTION, POLL 
> Cerrtype; 


typedef enum { 

CLIP_RECT, VIEWPORT, VIEWSURFACE 
} Cexttype; 


typedef struct { 

Cintertype style; 

Cflag visible; 

Cint color; 

Cint hatch_index; 

Cint pattern_index; 

Cint index; 

Clintype pstyle; 

Cfloat pwidth; 

Cint pcolor; 

> Cfillatt; 


typedef enum { 
OFF, ON 
> Cflag; 


typedef struct { 
Cint n; 

Cint *num; 
Casptype * value; 
> Cf laglist ; 


typedef float Cfloat; 

typedef enum { 

FREEZE, REMOVE 
y C freeze; 

typedef enum { 

LFT, CNTER, RGHT, NRMAL, CNT 
} Chaligntype; 

typedef int Cint; 
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typedef enum { 

NO_INPUT, ALWAYS-ON, SETTABLE, DEPENDS_ON_LID 
} Cinputability; 


typedef struct { 

Ccoor *xypt; 
Ccoorlist ^points; 
Cfloat val; 

Cint choice; 

Cchar ^string; 
Cpick *pick; 

} Cinrep; 


/* LOCATOR */ 

/* STROKE devices */ 
/* VALUATOR device */ 
/* CHOICE devices */ 
/* STRING device */ 

/* PICK devices V 


typedef enum { 

HOLLOW, SOLIDI, PATTERN, HATCH 
} Cintertype; 


typedef struct { 

Clogical sample; 

Cchangetype change; 

Cint numassoc; 

Cint *trigassoc; 

Clogical prompt; 

Clogical acknowledgement ; 

Cecho type 1st * echo ; 

Cchar *classdep; 

Cstatelist state; 
y Cliddescript ; 

typedef enum { 

RELEASE, NO_EVENTS, REQUEST_EVENT, RE SPONDEE VENT, QUEUE_EVENT 
} Clidstate; 

typedef struct { 

Clintype style; 

Cfloat width; 

Cint color; 

Cint index; 

> Clinatt; 

typedef enum { 

SOLID, DOTTED, DASHED, DASHED_DOTTED, DASH_DOT_DOTTED , LONG_DASHED 
} Clintype; 

typedef enum { 

L_TRUE , L_FALSE 
} Clogical; 
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typedef struct { 

Cmartype type; 

Cfloat size; 

Cint color; 

Cint index; 

} Cmarkatt; 

typedef enum { 

DOT, PLUS, ASTERISK, CIRCLE, X 
} Cmartype; 

typedef enum { 

SIMULTANEOUS_EVENT_FOLLOWS , SINGLE_EVENT 
} Cmesstype; 

typedef enum { 

RIGHT, LEFT, UP, DOWN 
} Cpathtype; 


typedef struct { 

Cint cur_index; 

Cint row; 

Cint column; 

Cint *colorlist; 

Ccoor *point; 

Cint dx; 

Cint dy; 

} Cpatternatt; 

typedef struct { 

int segid; /* segment */ 

int pickid; /* pick id */ 

} Cpick; 

typedef struct pixrect Cpixrect; 

typedef enum { 

STRING, CHARACTER, STROKE 
} Cprectype; 

typedef enum { 

PROMPT_ON, PROMPT_OFF 
} Cpromstate; 

typedef enum { 

NOT_ VALID, EMPTY, NON_EMPTY, ALMOST_FULL, FULL 
> Cqtype; 
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typed© f enum { 

ABSOLUTE, SCALED 
} Cspecmode; 


typedef struct { 

Clidstate state; 

Cpromstat© prompt; 
Cackstate acknowledgement; 
Cinrep * current; 

Cint n; 

Cint * triggers; 

Cechotype echotyp; 
Cechostate echosta; 

Cint echodat; 

} Cstatelist; 


typedef enum { 

NONE, REQUIRED_FUNCTIONS_ONLY, SOME_NON_REQUIRED_FUNCTIONS , 
ALL__NON__REQUIRED_FUNCTIONS 
} Csuptype; 

typedef struct { 

Cint fontset; 

Cint index; 

Cint current_font ; 

Cprectype precision; 

C float exp_factor; 

C float space; 

Cint color; 

Cint height; 

Cfloat basex; 

Cfloat basey; 

Cfloat upx; 

Cfloat upy; 

Cpathtype path; 

Chaligntype halign; 

Cvaligntype valign; 

Cfloat hcalind; 

Cfloat vcalind; 

> Ctextatt; 

typedef enum { 

FINAL, NOT.FINAL 
} Ctext final; 
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typed© f struct { 

Cchangetype change; 

Cassoclid *numassoc; 

Cint maxassoc; 

Cpromstate prompt; 

Cackstate acknowledgement; 

Cchar fi name; 

Cchar * des cr ip t i on ; 

} Ctrigdis; 

typedef struct { 

Cact state state; 

Cassoclid *assoc; 

} Ctrigstate; 

typedef enum { 

TOP, CAP, HALF, BASE, BOTTOM, NORMAL, CONT 
} Cvaligntype; 

typedef enum { 

INTEGER, REAL, BOTH 
} Cvdctype; 

typedef struct { 

Cchar screenname [DEVNAME SIZE] ; /* physical screen */ 

Cchar windowname [DEVNAME SIZE] ; /* window */ 

Cint windowfd; /* window file */ 

Cint retained; /* retained flag */ 

Cint dd; /* device */ 

Cint cmapsize; /* color map size */ 

Cchar cmapname [DEVNAME SIZE] ; /* color map name */ 

Cint flags; /* new flag */ 

Cchar **ptr; /* CGI tool descriptor */ 

} Cvwsurf; 
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Error Messages 


This appendix lists the error messages in numerical and alphabetical order. Furthermore, the 
probable cause of each error is given in the sentences following the error. In addition to explain- 
ing the error message, an initial suggestion for corrective action is given. In the title for each 
group of errors, the range of error numbers is given in parentheses after the title. If your appli- 
cation program is not behaving as you want it to, but does not generate error messages, then the 
table at the end of this appendix which lists commonly encountered problems and frequent 
causes may be helpful. 

D.l. Successful Return (0) 

0 NO_ERROR (0) 

Mo error. 

D.2. State Errors (1-5) 

1 ENOTCGCL CGI not in proper state: CGI shall be in state CGCL. A call 

to open_cgi was attempted when cgi was already open. Elimination of the error 
can be accomplished by removing the offending call to open__cgi. 

2 ENOTCGOP CGI not in proper state: CGI shall be in state CGOP. Every 

function except open_cgi requires that CGI be open. If this error is received, 
make sure that your application program has called open_cgi, or that it has not 
recently called cloae_cgi . 

3 ENOTVSOP CGI not in proper state: CGI shall be in state VSOP. The 

function which generated the error requires that at least one view surface be 
open. Corrective action would include either removing the most recent call to 
cloae_vws or by including a call to open_vwa. 

4 ENOTVSAC CGI not in proper state: CGI shall be in state FSAC. The 

function which generated the error requires that at least one view surface be 
active. Corrective action would include either removing the most recent call to 
deactivate_vwa or by including a call to activate_vwa. 

5 ENOTOPOP CGI not in proper state CGI shall b© in state CGOP 9 FSOP, 

or FSAC. The function which generated the error requires that SarnCGI is 
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at least initialized. If this error is received, make sure that your application 
program has called open_cgi, or that it has not recently called close_cgi. 

D.3. Control Errors (10-16) 

10 EVSIDINV Specified view surface name is Invalid, The view surface name 

specified by the name argument has never been opened or if it has been 

opened, it has since been closed. Corrective action involves opening the view 
surface or changing the value of the name argument. 

11 ENOWSTYP Specified view surface typ© do ©e not ©jsisfc. The application 

program has specified a type of view surface which is not supported by 
SunCGI. Corrective action involves changing the type of view surface. 

12 EVSISOPN Specified view surface is open. An attempt was made to open a 

view surface which is already open. Corrective action involves removing one 

call to open_vw3. 

13 EVSNOTOP Specified view surface not open. An attempt was made to close a 

view surface which is already closed. Corrective action involves removing one 
call to close_vw3. 

14 EVSISACT Specified view surface is active. An attempt was made to 

activate a view surface which is already activated. Corrective action involves 
removing one call to activate_vws. 

r 

15 EVSNTACT Specified view surface is not active. An attempt was made to 

deactivate a view surface which has already been deactivated. Corrective 
action involves removing one call to deactivate^vws. 

16 EINQALTL Inquiry arguments are longer than list. A call to inquiry negotia- 

tion function with indices greater than the number of supported functions was 
made. The returned list is always empty. Corrective action may be facilitated 
by obtaining the size of the list by using the inquire_device_class function. 

Do4. Coordinate Definition (20-24) 

20 EBADRCTD Rectangle definition is invalid. The application program has 

made a call to vdc_extent or devtce_viewport with the coordinates of both 
corners equal in the x or y dimensions or both. Corrective action involves 
changing one of the arguments to the function which generated the error so 
that the values of the two arguments are different in both the x and y dimen- 
sions. 

21 EBDVIEWP Viewport ±® not within Device Coordinates. A call to 

device_viewport has been made which specifies a viewport which is larger than 
the view surface. Corrective action involves making the arguments to 
device_viewport less than the view surface size. The size of the view surface can 
be obtained by calling the inquire_phyaical_coordinate_system function. 
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22 ECLIPTOL Clipping rsotangl® i® too large. The clipping rectangle would 

exceed the boundaries of VDC Space. Corrective action involves resetting the 
clipping rectangle to be within limits of VDC Space. 

23 ECLIPTOS Clipping reofcangl© im too small. The clipping rectangle would 

define an area of screen space smaller than one pixel. The clipping rectangle 
remains unchanged. Since the occurrence of this error is partially a function of 
the size of the view surface, changing the size of the view surface may be a 
viable alternative to changing the size of the clipping rectangle. 

24 EVDCSDIL VDC spae© definition is illegal. One or more of the arguments to 

the vdc_extent function exceeds the acceptable limits (-32767 to 32767) or coor- 
dinates of the lower-left hand corner are greater than the coordinates of the 
upper-right hand corner. Corrective action involves changing the arguments to 

vdc_extent. 

D.5. Output Attributes (30-51) 

30 EBTBUNDL ASS' i® BUMBLED. Error 16 is generated when attempting to call an indivi- 

dual attribute function when the attributes are specified by entries in the attri- 
bute environment table. Calls to these functions have no effect on the current 
attributes. Corrective action includes resetting the attribute environment selec- 
tor to BUNDLED by using the aet_attribute_environment_selector function. 

31 EBBDTBDI Bundle table index out ©f rang®. The entry in the bundle table 

exceeds the size of the table. The only corrective action is to change the value 
of the index argument. 

32 EBTUNDEF Bundle table index is undefined. The entry in the attribute 

environment table specified by the most recent call to 
aet_attribute_environment_table_index has not been defined by SunCGI or the 
application program. Corrective action includes defining the entry by calling 

define_attribute__environment_selector_index. 

33 EBADLINX Polyline index is invalid. The polyline bundle is not defined. Correc- 

tive action involves changing the index argument to polyline_bundle_index, or 
by defining the polyline bundle index. 

34 EBD WIDTH Width must b® nonnegativ© . The width of a perimeter or line must be 

greater than or equal to zero. The current value of the perimeter width or line 
width remains unchanged. Changing the value of the width argument to a 
non-negative value will correct this error. 

35 ECINDXLZ Color index is less than gero. The value of the index argument to 

one of the attribute functions or the color entry in one of the bundles is negar 
tive. Corrective action involves changing the value of the color. 

36 EBADCOLX Color index is invalid. The color index argument to one of the attri- 

bute functions or the color entry in one of the bundles is not defined in the 
colormap. Indices in the color lookup table must be between 0 and 255 for the 
Sun 8-bit per pixel frame buffer. Any color specification outside of this range is 
ignored. Corrective action involves changing the value of the color. 
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37 EBADMRKX 

38 EBADSIZE 

39 EBADFABX 

40 EPATARTL 

41 EPATSZTS 

42 ESTYLLEZ 

43 ENOPATNX 

44 EPATITOL 

45 EBADTXTX 

46 EBDCHRIX 

47 ETXTFLIN 

48 ECEXFOOR 

49 ECHHTLEZ 


Polymarker index is invalid. The polymarker bundle is not defined. 

Corrective action involves changing the index argument to 

polymarker Jbundle_index, or by defining the polymarker bundle index. 

Sis© must b© nonneg&tiv©. The size of a marker or line must be 
greater or equal to zero. The current value of the marker size remains 
unchanged. Changing the value of the size argument to a non-negative value 
will correct this error. 

pill area index is invalid. The fill area bundle is not defined. 

Corrective action involves changing the index argument to 

filLarea_bundle_index, or by defining the polymarker bundle index. 

Pattern array too large . The pattern array must contain less than 257 
elements. The pattern is not entered into the pattern table. Corrective action 
involves designing a new pattern. 

Pattern sis® to© small. The pattern size must be at least two-by-two. 
The pattern is not entered into the pattern table. Corrective action could 
include designing a new pattern which includes several replications of the origi- 
nal pattern. 

Style (pattern or hatch) index is less than zero. All indices 
in the pattern table must be positive. To fix this mistake, change the argument 
to the pattern__index or the hatch_index or the entries in the bundle table. 

Pattern table index not defined. The argument to the hatch_index 
or pattern_index function or the entry bundle table should be reset to 
correspond to a defined value. 

Pattern table index too large. The index argument to pattern_table 
exceeded the bounds of the pattern table. The pattern is not entered into the 
pattern table. Redefining the pattern index to be between one and ten will 
eliminate the error. 

Text index is invalid. The text bundle is not defined. Corrective 
action involves changing the index argument to text_bundle_mdex, or by 
defining the text bundle index. 

Character index is undefined. All other character indices besides 1 
are undefined in SunCGI. The new character index is simply ignored. You are 
advised to ignore the character_index function entirely. 

Text font is invalid. The text fonts range from 1 to 6. All other 
integers do not correspond to actual fonts. Corrective action involves changing 
the argument to the text_font_index function or resetting the font index in the 
text bundle 

Expansion factor is out ©f rang©. The character expansion factor 
or the character space expansion factor would result in a character or a space 
which would exceed the bounds of the screen or would result in a character 
smaller than the limitations of the character drawing software. To eliminate 
this error, reset the offending value to within an acceptable range (0. 1-2.0 are 
reasonable guidelines). 

Character height is l©s® than or equal to zero. The character 
height must be positive. Corrective action involves changing the argument to 
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the character height function or the element of the text bundle. 

50 ECHRUPVZ Length ©f character up sector or character has® vaofcor is 

sero. Both the character up vector and the character base vector must be 
nonzero. Corrective action involves changing the arguments to the 
character_orientation function or the element of the text bundles. 

51 ECOLRNGE RGB values must b ® between 0 and 255. The red, green, and blue 

values are only defined between 0 and 255. The call to color_table which pro- 
duced the error is ignored. Corrective action requires respecifying the values of 
the arguments to color_table. 

D.6. Output Primitives (60-70) 

60 ENMPTSTL Number of points is too large. The number of points exceeds 255. 

Change the n element of the eoorlist structure to a value less than or equal 
to 255. 

61 EPLMTWPT polylines must have at least two points. Change the n element 

of the eoorlist structure to a value greater than 2 and add the correspond- 
ing points to the ptlist element. 

62 EPLMTHPT Polygons must have at least three points. Change the n element 

of the eoorlist structure to a value greater than or equal to 3 and add the 
corresponding points to the ptlist element. 

63 EGPLISFL Global polygon list is full. The number of points on the global 

polygon list exceeds 256. The points which exceed 256 are ignored. This error 
can be corrected by inserting a call to polygon (which clears the global polygon 
list by displaying its contents) before the call to partial_polygon which caused 
the overflow. 

64 EARCPNCI Arc points do not li© on circle. The starting and ending points of 

either an open or close circular arc do not lie on the perimeter of the circle 
described by the arguments cl and rad. If this error occurs, the arc is not 
drawn. Corrective action may include determination of the endpoints with the 
application program (for example c2.x = rad*cos(start_angle);). 

65 EARCPNEL Arc points do not li© on ellipse. The starting and ending points of 

either an open or close elliptical arc do not lie on the perimeter of the ellipse 
described by the arguments cl,c2, and cS. If this error occurs, the arc is not 
drawn. Corrective action may include determination of the endpoints with the 
application program (see error II). 

66 ECELLATS C©11 array dimensions to 9 dy ar© too small. The dimensions of 

the cell array are too small for a cell array element to be mapped onto one 
pixel of the view surface. The cell array is not drawn. This error depends on 
the physical size of the view surface as well as the limits of VDC Space. There- 
fore, corrective action might require changing the size of the view surface, VDC 
Space, or both. 

67 ECELLPOS Cell array dimensions must b@ positive. Negative cell array 

dimensions are not permitted. Corrective action requires changing the parame- 
ters to the cell array function. 
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69 EVALOVWS Valu© outside of view surface. A coordinate of a pixel array is out- 

side the physical range of the view surface. The pixel array is not drawn. 
Change the arguments to the pixeLarray or bitblt_source_array 

70 EPXNOTCR Pixrect not created. One of the bitblt functions required a user-defined 

pixrect, and that pixrect had not been created. Corrective action involves 
creating a pixrect in your application program before calling the offending bitblt 
function. 

0.7. Input (80-97) 

80 EINDNOEX Input device does not exist. The input device specification (specified 

by the devclass and devnum arguments of most input functions) does not exist. 
Corrective action involves resetting the device specification to a valid device. 

81 EINDINIT Input device not initialised. A call to an input device function 

specified a device which was not initialized. Calls which generate this error 
have no effect. A call to initialize_input„device should be inserted before the 
call generating the error. 

82 EINDALIN Input device already initialised. An attempt to initialize a device 

which has previously been initialized. The parameters to the offending call to 
initiaiize_input_device are ignored. Removing the offending call to 
initialize_input_device will correct this error. 

83 EINASAEX Association already exists. An attempt is being made to bind the 

input device to a trigger to which it has been previously bound. The status of 
the input device trigger are unchanged. This error is purely informational and 
no corrective action is required. 

84 EINAIIMP Association i® impossible. An attempt is being made to bind the 

input device to a trigger to which it cannot be bound. For example a 
IC_STRING device cannot be bound to a mouse button. To eliminate this 
error, change the arguments to the offending call of the associate function. 

85 EINNTASD Association does not exist. An attempt to set-up call an input func- 

tion which specifies a device with no associated triggers was made. The 
offending call is ignored. Corrective action involves calling associate before the 
offending call is issued. 

86 EINTRNEX Trigger doe® not exist. An attempt was made to associate or inquire 

about a trigger which has a number less than one or greater than five. The 
offending call is ignored. To eliminate the error, change the trigger number. 

87 EINNECHO Input device does not echo. CHOICE devices do not support echo. 

Corrective action requires removing the call to echo_on from the application 
program. 

88 EINECHON Echo already on. A call to echo_on has been made to a device whose echo- 

ing ability has already been activated. To stop generation of the error either 
remove the offending call or change the arguments to specify a device whose 
echo is currently off. 
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89 EINEINCP Echo incompatible with existing echos . Although SunCGI can 

support certain combinations of echos (such as ICjSTRING and 
ICLLOCATOR), not all combinations are supported. The easiest remedy is to 
remove the most recent call to echo_on from the application program. 

90 EINERVWS Ichor egion larger than view our face. Error 91 is generated when 

the rectangle defined by the echoregion argument exceeds the limits of VDC 
Space. To eliminate this error, change the values to the echoregion argument to 
be within the confines of VDC Space. 

91 EINETNSU Echo type not supported. All devices except the ICjSTROKE device 

only support one type of echo. Therefore, assigning a value to echotype other 
than zero or one will produce an error for any device except IC_STROKE. 
Corrective action involves changing the value of the echotype argument. 

92 E1NENOTO Echo not on. The device echoing has not been turned on. Either remove 

the call to echo_off, turn the echo on, or change the device specification. 

93 EIAEVNEN Events already enabled. Events have already been enabled for the 

specified device. The solution is to remove the offending call to enable_events. 

94 EINEVNEN Events not enabled. Events have not been enabled for the specified dev- 

ice. The solution is to include a call to enable_events before a call to the 
await_event, sample_event, or request_event function is made with the specified 
device as input parameter. 

95 EBADDATA Contents of input data record are invalid. The value argument 

of initializejlid function is out of range or is the wrong type. The solution is to 
change the contents value argument. 

96 ESTRS1ZE Length of initial string is greater than the implementa- 

tion defined maximum. The initial string in the value argument is greater 
than 80 characters. Shorten the string. 

97 EINQOVFL Input queue has overflowed. The event queue can no longer record 

input events. Solutions include flushing the event queue or dequeueing events 
with the await_event, sample_event, or request_event function. 

D.8. Implementation Dependent (110) 

110 EMEMSPAC 

Space allocation has failed. A function which was supposed to work 
has failed. The only action which you can take is to eliminate other processes 
which may be using memory. If you have eliminated all other processes, and 
this error is still generated, please contact SUN Microsystems. 
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D.9. Possible Causes of Visual Errors 


Table D-l: Possible Causes of Visual Errors 


Behavior 


Possible Cause 

Segmentation fault for open_vws 

a. 

devdd argument for open_vws is declared as 
a pointer (the address of devdd should be 
passed). 

No primitives displayed 

a. 

View surface not initialized. 


b. 

View surface not active. 


c. 

VDC to device coordinate mapping makes 
objects too small. 


d. 

Clipping rectangle is too small and clipping 
is ON. 


e. 

Perimeter visibility is set to OFF and interi- 
or style is set to HOLLOW. 


f. 

line_color or filLcolor is set to background 
color. 

Primitives displayed on undesired view sur- 

a. 

Undesired view surfaces have not been deac- 

faces 


tivated. 

Segmentation fault for inquiry functions 

a. 

passing variable instead of address ( & ) of 
variable. 
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Table D-2: Primitive-Specific Errors 


Behavior 


Possible Cause 

Polylines or polymarkers aren’t displayed. 

a. 

Width or size is zero. 


b. 

Color is the same as background. 

Polygon borders aren’t displayed. 

a* 

Width is zero. 


b. 

Color is the same as background. 


c. 

Perimeter visibility is set to OFF. 

Circles aren’t displayed. 

a. 

Width or size is zero. 


b. 

Color is the same as background. 

Ellipses aren’t displayed. 

a. 

Width or size is zero. 


b. 

Color is the same as background. 

Text isn’t displayed. 

a. 

Width or size is zero. 


b. 

Color is the same as background. 


c. 

character height is too small. 


d. 

coordinates are outside the range of VDC 



Space or the clipping rectangle. 

Cell arrays aren’t displayed. 

a. 

Dx or dy arguments are too small. 


b. 

Color is the same as background. 

Cell arrays aren’t displayed on all active 

a. 

Mapping from cell size to view surface for 

view surfaces. 


smaller view surfaces is too small. 

Pixel arrays aren’t displayed. 

a. 

Location is outside of view surface or clip- 



ping rectangle. 


b. 

Color is the same as background. 

Bitblts aren’t displayed. 

a. 

Width or size is zero. 


b. 

Color is the same as background. 
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Table D-3: Attribute Errors 


Behavior 


Possible Cause 

Attribute setting has no effect 

a. 

attribute ASF is set to BUNDLED. 

Text attributes have no effect 

a. 

text precision is set to CHARACTER. 


b. 

attribute ASF is set to BUNDLED. 

PATTERN fill is the same as HATCH 

a. 

patternjndex and hatch__index are identical 


b. 

pattern_jsize is too small 

PATTERN fill is different on different view 
surfaces. 

a. 

View surfaces are of different size. 


Table D-4: Input-specific Errors 


Behavior 


Possible Cause 

Input device does not report 

a. 

device not initialized 

Input device does not echo 

a. 

echo not initialized 

Input device does not echo on whole view 
surface 

a. 

echo region not set to whole view surface. 
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Appendix E 


Sample Program 


E.l. Martini Glass 

The following program draws a Martini glass. The figure drawn by this program is identical to 
figure drawn by the example given in the appendix of the SunCore manual. It is suggested that 
novice users attempt to write this program to familiarize themselves with SunCGI. 
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tifndef lint 

static char sccsid[] = (#) glass .c 1.1 84/11/01 Copyr 1984 Sun Micro"; 

#endif 

#includ© <cgidefs.h> 

static Ccoorlist martinilist; 

static Ccoor glass_coords [10] = { 0,0 , 

- 10,0 

- 1.1 

- 1,20 

-15,35 

15,35 

1,20 

1,1 

10,0 

0,0 }; 

static Ccoor water _coords [2] = {-12,33 

12,33 }; 

static Ccoor vpll = {-50,-10}-; 
static Ccoor vpur = {50,80}; 


Cint name; 

main () 

{ 

Cvwsurf device; 


dev ice . dd=PI XWI NDD ; 

open_cgi(); /* initialize CGI */ 

open_vws (&name, ^device) ; /* open view surface */ 

vdc_extent (&vpll , fivpur) ; /* reset VDC space */ 

martinilist .ptlist=glass_coords; /* load polyline structure */ 
martinilist .n=10; 

polyline (^martinilist) ; /* draw glass */ 
mar t ini 1 ist.pt 1 ist=water__coor ds ; 
martinilist .n=2; /* draw waterline */ 
polyline (Smart ini list) ; 

sleep (10); /* display for 10 seconds */ 
close_vws (name) ; /* exit */ 
close__cgi () ; 
exit (0) ; 

> 
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CGI and Pixwins calls can be integrated in a single application program by using the Cgipw 
functions. However, the CGI standard does not provide for facilities for dealing with multiple 
overlapping windows. Many users would like to have the richness of CGI’s primitives combined 
with Pixwin’s ability to automatically take care of multiple (potentially overlapping) windows. 

If you decide to use CGI and Pixwins, you may not use the standard SunCGI calls. Instead 
you should use cgipw calls. For example, cgipw_polyline should be used instead of poly- 
line. Note that cgipw functions do not return error codes. 

Using SunCGI and Pixwins involves using the basic CGI primitives to include a CGI pixwin 
descriptor (type Ccgiwin) as the first argument. The routines implementing the CGI standard 
output and attribute functions for SunCGI functions take a structure containing a specific 
pixwin and attribute pointer as their first argument. However, the file <cgipw.h> should be 
included instead of <cgidefs.h> in the application program. The four functions 
op en_p w_c g i , open_cgi_pw, close_cgi_pw, and close_pw_cgi are necessary for 
managing the SunCGI/Pizwin interface. 


F.l. open_pw_cgi 


Cerror open_pw_cgi () 

open_pw_cgi puts CGI in a known internal state by setting the attributes to the default values 
and setting the NDC to device coordinate mapping to 1:1. Therefore, unless the application pro- 
gram changes the mapping by explicitly calling CGI functions to reset the NDC to device coordi- 
nate mapping, all input and output primitives will use device coordinates. The origin of the dev- 
ice coordinates is in the upper left-hand corner instead of the lower left-hand corner. No stan- 
dard errors are specified. If open_pv_cgi returns a nonzero result, then the initialization 
failed. 


F.2. open_c gi__pw 
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Cerror open_cgi_pw(pw, desc, name) 
pixwin 4 pw; /* pixwin */ 

Ccgiwin *desc; /* CGI pixwin descriptor */ 

Cint name; 

open_cgi_pw makes the pixwin pointed to by pw known to the internals of CGI. Calls to all 
CGI primitives will affect this pixwin. Desc is a pointer to a CGI pixwin which is used as the first 
argument to cgipw function. However, CGI does not guarantee that a pixwin exists or is any 
other way properly initialized. Calls may also be made to any pixwin function (see example pro- 
gram). Multiple calls to open_cgi_pv will result in primitives being displayed on multiple 
view surfaces. Attributes are local and apply only to the specified pixwins which have been 
opened by using open_cgi_pw. 


F.3. close_cgi„pw 


Cerror close_cgi_pw (desc) 

Ccgiwin *d@sc; /* CGI pixwin descriptor */ 

close_cgi_pw takes the CGI pixwin descriptor desc as an argument and removes it from the 
list of pixwins that CGI writes to. The pixwin is not closed. 


F.4. close__pw_cgi 


Cerror close__pw_cgi () 

close_pw_cgi takes care of leaving CGI in an orderly state. This function should be called 
before exiting the application program. 


F.5. Using Cgipw 

After calling the two initialization functions (open_pw_cgi, open_cgi_pw) the user may call 
both pixwin and SunCGI primitives as specified in their respective manuals. Signals are not 
handled by SunCGI when it is used with pixwins. No error handling is done by cgipw func- 
tions — this makes cgipw more efficient but errors must be detected by the programmer. 
Therefore, the application program must insure that the NDC to device coordinate mapping is 
changed when the window size is changed. The application program should not use both 
SunCGI and window system input functions, since both SunCGI and the window system share 
a common event queue. For example, events handled by a SunCGI function will not be han- 
dled by a window system called after the SunCGI call. 

The cgipw functions is given in the table below. If one of the functions that you want to use is 
not listed, then you should use the normal SunCGI function. Most of the functions listed below 
are output and attribute functions; however, the tracking functions are listed so that you can 
control which surfaces input devices echo on. The arguments of the Cgipw functions are the 
same as those of the SunCGI functions except that the first argument is always the desc argu- 
ment which is of type Ccgiwin. Desc is a pointer to pixwin descriptor obtained from the 
open_cgi_pw function. 
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F.6. List of Cgipw Functions 


Table F-l: List of Cgipw Functions 


CGI Function Name 


Cgipw Function Name 


append_text (f lag, tstring) 


cgipw_append_t ext (desc, flag, tstring) 


cell_array (p, q, r , dx, dy, colorind) 

cgipw_cel l_array (desc, p, q, r, dx, dy, colorind) 

char acter„expansion_ factor (sfac) 


cgipw_character„expansion„f actor (desc, sfac) 


charact©r_height (height) 


cgipw_character ..height (desc, height) 


character ..orientation (xup, yup, xbase. 

cgipw_charact©r_orientat ion (desc, xup, yup, xbase. 

ybase) 


ybase) 


character_path (path) 


cgipw_character_path (desc, path) 


char actor _set_index (index) 


cgipw_character_set_index (desc, index) 


character_spacing (spcratio) 


cgipw_char acter_spacing (desc , spcratio) 


circle (cl, rad) 


cgipw__circl© (desc, cl, rad) 


circular__arc_3pt (cl, c2, c3) 


cgipw_circular_arc„3pt (desc, cl, c2, c3) 


circular _arc_3pt_close (cl, c2. 

c3. 

cgipw_circular__arc_3pt_c lose (desc, cl, c2. 

c3. 

close) 


close) 


circular_arc_center (cl, c2x, c2y. 

c3x. 

cgipw_circular_arc_center (desc, cl, c2x, c2y. 

c3x. 

c3y, rad) 


c3y, rad) 


circular_arc_center_close (cl. 

c2x. 

cgipw_circular_arc_center_close (desc, cl. 

c2x. 

c2y, c3x, c3y, rad, close) 


c2y, c3x, c3y, rad, close) 


def ine_bundle_index (index) 


cgipw_def ine_bundle_ index (desc, index) 


dis joint_j?olyline (polycoors) 


cgipw_dis joint_polylin© (desc, polycoors) 


ellipso(cl, majx, miny) 


cgipw_e 11 ipse (desc, cl, majx, miny) 


©lliptical_arc (cl, sx, sy, ex. 

®y. 

cgipw__elliptical_arc (desc, cl, sx, sy, ex. 


majx, miny) 


majx, miny) 


©lliptical_arc_clos© (cl, sx, sy. 

©X, 

cgipw__elliptical_arc_c lose (desc, cl, sx, sy. 

ex. 

©y, majx, miny, close) 


©y, majx, miny, close) 


f i 1 l_ar ea_bund le_index ( index) 


cgipw_f il l_area_bundle_index (desc, index) 


fill_color (color) 


cgipw_.fi ll__co lor (desc, color) 


f ixed__font (index) 


cgipw__f ixed__f ont (desc , index) 


hatch_index (index) 


cgipw_hatch_index(desc, index); 


inquir©_asp©ct_source_f lags () 


cgipw_ inqui re_aspect_s our ce_ flags (desc) ; 


inquir©__drawing__mod© (visibility. 


cgipw__inquire_drawing_mod© (desc, visibility. 

source, destination, combination) 


source, destination, combination) 


inquire_fil l_area_attr ibutes () 


cgipw_inquire_fill_area_attr ibutes (desc) ; 


inquire_line_attr ibutes () 


cgipw_inquire_line__attr ibutes (desc) ; 


inquir e__marker_attr ibutes () 


cgipw_inquire_marker_attr ibutes (desc) ; 


inquir ©_pattern_attr ibutes () 


cgipw_inquire_pattern_attr ibutes (desc) ; 


inquire_pixel_array (p, m, n, colorind) 

cgipw_inquire_pixel_array (desc, p, m, n, colorind) 

inquir e_text_attr ibutes () 


cgipw__inqu.tr e__text„attr ibutes (desc) ; 
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CGI Function Name 

Cgipw Function Name 

i n qu i r©_t ext _ex tent (tstring, nextchar , 
concat, lleft, uleft, uright) 
inter ior_styl© (istyle, perimvis) 
line_color (index) 
line_endstyl© (ttyp) 
line_type (ttyp) 

cgipw_inquir©_text_extent (desc, tstring, next char , 
concat, lleft, uleft, uright) 
cgipv__interior_style (desc, istyl®, perimvis) 
cgipw__line_color (desc, index) 
cgipw_l ine_endsty 1© (desc , ttyp) 
cgipv_ 1 ine_typ© (desc , ttyp) 

line_width (index) 

line_width_specif ication__mod© (mod©) 
marker__color (index) 
marker_s iz© ( index) 

marker_size_specif ication_mod© (mod©) 

cgipw_line_width (desc, index) 

cgipw_l in©_if idth_speci f icat ion_modo (desc , mode) 
cgipw_marker_co lor (desc, index) 
cgipw_marker_s iz© (desc , index) 

cgipw_marker__size_specif ication_mod© (desc, mode) 

marker_type (ttyp) 
patter n_index (index) 
pattern_referonce_point (open) 
patter n_siz© (dx, dy) 

patter notable (index, m, n, colorind) 

cgipw_marker_type (desc, ttyp) 
cgipw_pattern_index (desc, index) ; 
cgipw_pattern_jrefer©nce^point (desc, open) 
cgipw_patt©rn_siz9 (desc, dx, dy) 

cgipw_pattern_table (desc, index, m, n, colorind) 

per im©t©r_color (index) 
per imeter_typ© (ttyp) 
per imeter_width (index) 

per imeter_width_specif ication_mode (mod©) 

pixel_array (pcell , m, n, colorind) 

cgipw_perimeter_color (desc, index) 

cgipw_per imeter_typ© (desc , ttyp) 

cglpw_p©r lmeter_vidth (desc, index) 

cgipw_per imeter_vidth_spec i f icat ion_mode (desc , 

mode) 

cgipw_pixel_ar ray (desc, pcell, m, n, colorind) 

polygon (polycoors) 
polyline (polycoors) 
polyline_bundle__index (index) 
polymarker (polycoors) 
polymarker_bundle_Index (index) 

cgipw_polygon (desc, polycoors) 
cgipw_poly line (desc, polycoors) 
cgipw_po ly 1 ine_bundle_index (desc , index) 
cgipw_po lymarker (desc, polycoors) 
cgipw_po lymarker_bund le_I ndox (desc, index) 

rectangle (lrc, ulc) 
set_asp©ct_source_f lags (flags) 
text (cl, tstring) 

textual ignment (halign, valign, 

hcalind, vealind) 
text_bundle_ index (index) 

cgipw_rectangle (desc, lrc, ulc) 
cgipw__set_aspect_s our ce_ flags (desc, flags) 
cgip^_text (desc, cl, tstring) 

cgipw_text_alignment (desc, halign, valign, 

hcalind, vealind) 

cgipw_text_bundle_index (desc, index) 

text_color (index) 

text_font_index (index) 

text_precision (ttyp) 

track_of f (dove lass, devnum) 

track_on (devclass, tracktype, trackre- 

gion, value) 

cgipw_text_co lor (desc, index) 
cgipv_text_font_index (desc, index) 
cgipw_text_precision (desc, ttyp) 
cgipv_track_of f (desc, devclass, devnum) 
cgipv_track_on (desc, devclass, tracktype, track re- 
gion, value) 

vdnutext (cl, flag, tstring) 

cgipv_vdnL_text (desc, cl, flag, tstring) 
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F.7. Example Program 


#includ© <cgipw .h> 

#includ© <suntool/gf xsw . h> 

struct pixwin *mypw; 
struct gfxsubwindow *mine; 

main () 

{ 

Ccgiwin vpw; 

Ccoor bottom; 

Ccoor top ; 
int name; 

int op ; 

min© = gfxsw_init (0, 0) ; 
gfxsw_getr©tained (mine) ; 
mypw = min©- >gfx_pixwin ; 

pw_wr iteback ground (mypw , 0 , 0 , mypw- >pw_prret ained - >pr_s iz© . x , 
mypw- >pw_prretained- >pr_siz© . y , PIX_CLR) ; 
open_pw_cgi () ; 

open_cgi_pw (mypw, &vpw, &naxn©) ; 
op = PIX_C0L0R(1) | PIX_SRC; 

pw_write (mypw, 0, 0, 100, 100, op, 0, 0, 0); 

bottom. x = 300; 

bottom. y = 100; 

top.x = 200; 

top .y = 0; 

cgipw_interior_style (&vpw, S0LIDI, ON) ; 
cgipw_rect angle (&vpw, ^bottom, &top) ; 
sleep (10) ; 
close_cgi_pw (name) ; 
close_pw_cgi () ; 

> 
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Using SunCGI with Fortran-77 Programs 


All functions provided in SunCGI may be called from FORTRAN-77 programs by linking them 
with the / uar/lib/libcgi77.a library. This is done by using the /77 compiler with a command 
line such as: 

tutorial% f 77 -o grab grab.f -lcgi77 -lcgi -lsmwindow -Ipi&reet -1m 

where grab./ is the FORTRAN source program. Note that /usr/lib/libcgLa must be linked with 
the program (the —lcgi option), and /uar/lib/libcgi77.a must come before it (the — lcgi77 
option). 

Defined constants may be referenced in source programs by including cgidefs77 .h. In a FOR- 
TRAN program, this must be done via a source statement like: 

include 'cgidefs77 .h' 

This include statement must be in each FORTRAN program unit which uses the defined constants, 
not just once in each source program file. 

In the Sun release of FORTRAN-77, names are restricted to sixteen characters in length and may 
not contain the underline character. For this reason, FORTRAN programs must use abbreviated 
names to call the corresponding SunCGI functions. The correspondence between the full 
SunCGI names and the FORTRAN names appears later in this appendix. In addition, FORTRAN- 
77 declarations for all SunCGI functions appear at the end of this appendix. 


G.l. Programming Tips 

• The abbreviated names of the SunCGI functions are less readable than the full length names 
because the underline character cannot be used in the FORTRAN names. However, since FOR- 
TRAN doesn’t distinguish between upper-case and lower-case letters in names, upper-case char- 
acters can be used to improve readability. There is an example of this later in this appendix. 

• Character strings passed from FORTRAN programs to SunCGI cannot be longer than 256 
characters. 

® FORTRAN passes all arguments by reference. Although some SunCGI functions receive argu- 
ments by value, the FORTRAN programmer need not worry about this. The interface routines 
in / v»r/lib/libcgi77.a handle this situation correctly. When in doubt, look at the FORTRAN 
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declarations for SunCGI functions at the end of this appendix. 

o Some SunCGI structures contain both int’s and float’s. For instance, the argument to 
inquire_viewing_parameters contains both int’s and float’s. This can be handled in 
FORTRAN by declaring a real array and an integer array and making them share storage 
by using an equivalence statement. Following the call to the inquiry function, the real 
components can be accessed using the real array and the integer components can be 
accessed using the integer array. 

o Since FORTRAN does not distinguish between upper-case letters and lower-case letters in 
identifiers, any FORTRAN program unit which includes the cgidef«77.h header file cannot use 
the same spelling as any constant defined in that header file, regardless of case. 


G.2. Example Program 

This example is the FORTRAN equivalent of the very simple program for drawing a martini glass. 


include 1 cgid©fs77 .h* 

integer vsurf (VWSURFSIZE) 
integer name 

integer glassdx(9), glassdy(9) 

data glassdx /— 10, 9, 0, — 14, 30, —14, 0, 9, — 10/ 

data glassdy /0, 1, 19, 15, 0, — 15, — 19, — 1, 0/ 

integer waterdx(9), waterdy(9) 

data water dx /— 10, 9, 0, —14, 30, —14, 0, 9, —10/ 

data waterdy /0, 1,19,15,0,-15, —19 , — 1 , 0/ 


c 

initialize CGI 




call cfopencgi 



c 

open the view surface 




call cfopenvws (name, , PIXWINDD, 


c 

reset VDC space 




call cfvdcext (vpll , vpur) 



c 

draw r glass 




call cfpolyline (glassdx. 

glassdy. 

10) 

c 

draw water surface 




call cfpolyline (waterdx. 

waterdy. 

9) 

c 

display for 10 seconds 




call sleep (10) 



c 

close the view surface 




call cfclosevws (name) 



c 

close cgi and exit 




call cfclosecgi 



c 

end 
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G.3. Correspondence Between C Names and FORTRAN Names 


Correspondence Between C Names and FORTRAN Names 

Long Name 

FORTRAN Equivalent 

activate.vws 

append_text 

associate 

await_event 

bitblt_pattern_array 

cfactvws 
cf apt ext 
cfassoc 

cfawaitev 

cfbtblpatarr 

bitblt_patterned_sourc©__array 

bitblt_source_array 

cel l_array 

char acter_expansion_ factor 
character_height 

cfbtblpatsouarr 

cfbtblsouarr 

cfcellarr 
cf char exp fac 
c f char height 

character_orientation 

character_path 

character_set_index 

character_spacing 

circle 

c f charor ientation 
cfcharpath 
cfcharsetix 
c f charspacing 
cfcircl© 

circular_arc_3pt 

circular_arc_3pt_close 

circular_arc_center 

circular_arc_center_close 

clear_control 

c f circarcthree 

cfcircarcthreecl 
c f circarccent 
cfcircarccentcl 
cfclrcont 

clear_view_sur face 
c 1 ip_indic ator 
clip_rect angle 
close__cgi 
close__vws 

cfclrvws 

cfclipind 

cfcliprect 

cfclosecgi 

cfclosevws 

color_table 

deactivate_vws 

de f ine Jbundle_index 

device_viewport 

disab 1 e_events 

cfcotabla 

cfdeactvws 

cfde fbundix 

cfdevvpt 

cfdaevents 

dis joint _poly line 
dissociate 
echo_of f 
echo_on 
echo_update 

cfdpolyline 

cfdissoc 

cfechoof f 

cfechoon 

cfechoupd 

ellipse 

el liptical_arc 

cfellips© 

cfelliparc 
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Correspondence Between C Names and FORTRAN Names 

Long Name FORTRAN Equivalent 

Qlliptical_arc_close 
enab 1 e_event s 
f il l_area_bundl©_index 

cfelliparccl 

cfenevents 

cf f lareabundix 

fill_color 

fixed_font 

f 1 ush_e vent _queue 

get_ 1 ast_requested_ input 

hard_reset 

cf f lcolor 

cf fixed font 
c f f lusheventqu 
cfgetlastreqinp 
cfhardrst 

hatch_index 
initialize__lid 
initiate__request 
inquire_aspect_source_ flags 
inquire_Joitblt_a 1 ignments 

cfhatchix 

cfinitlid 

cfinitreq 

cfqasfs 

cfqbtblalign 

inquire_ce 1 l_ar r ay 
inquire_device_bitmap 
inquire_device_class 
inquire_device_identi f ication 
inquire_draving_mode 

cfqcellarr 

cfqdevbtmp 

cfqdevclass 

cfqdevid 

cfqdrawmode 

inquire_event_queue 
inquire_f il l_area_attributes 
inquire_input„capabi 1 it ies 
inquire_lid_capabilities 
inquire.^ 1 id_state_l ist 

cfqevque 
cfqf lareaatts 
cfqinpcaps 
cfqlidcaps 
cfqlidstate 

inquire_l id_state_l ist 
inquire_line_attributes 
inquire_marker_attributes 
inquire_output_capabilities 
inquire_output_ f unct ion_set 

cfqlidstatelis 
cfqlnatts 
cfqmkatts 
cfqoutcap 
c f qout f unset 

inquire_pattern_attributes 

inquire_physical_coordinate_system 

inquire_pixel__array 

inquire_text_attributes 

inquire_text_extent 

cfqpatatts 
c f qphyscsys 
cfqpixarr 
cfqtextatts 
cfqtextext 

inquire_tr igger_capabi 1 it ies 

inquire_trigger_state 

inquire__vdc_type 

interior_styl© 

line_color 

cfqftrigcaps 
cfqtrigstat© 
cfqvdctype 
cfint style 
cf Incolor 

1 ine_endsty 1 e 

cf lnendstyle 
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Correspondence Between C Names and FORTRAN Names 

Long Name 

FORTRAN Equivalent 

line_type 

cf lntype 

line__vidth 

cf lnwidth 

line_vidth_specification_mode 

c f 1 n v i dthsp e cmo de 

marker.color 

cfmkcolor 

marker_size 

cfmksize 

marker_size_speci f ication_mode 

c fmksizespecmode 

marker_type 

c fmktype 

open_cgi 

cfopencgi 

open.vvs 

cfopenvws 

partial_polygon 

cfppolygon 

pattern_index 

cfpatix 

pattern_re f erence_point 

cfpatrefpt 

pattern_size 

cfpatsize 

pattern_table 

cfpattable 

perimeter.color 

cfperimcolor 

perimeter_type 

cfperimtype 

perimeter_width 

c fper imvidth 

perimeter_width_specification_mode 

c fper imwidthspecmode 

pixel_array 

cfpixarr 

polygon 

cfpolygon 

polyline 

cfpolyline 

polyline_bundle__index 

cfpolylnbundix 

polymarker 

cfpolymarker 

polymarker_bundle_index 

c f po lymkbundix 

rectangle 

cfrectangle 

release_input_device 

cfrelidev 

request_input 

cfreqinp 

reset_to_de faults 

cfrsttode fs 

samp 1 e_ input 

cfsampinp 

se 1 ect ive_ f 1 ush.o f _event_ queue 

cfselect f lusheventqu 

set_aspect_source_ flags 

cfsaspsou flags 

set_de f ault_tr igger_associations 

c f sde f atr igassoc 

set_drawing_mode 

cfsdrawmode 

set_error_warning_mask 

c fserrwarnmk 

set_global_drawing__mode 

cfsgldrawmode 

set_initia l_va lue 

cfsinitval 

set_up_sigvinch 

cfsupsig 

set_va luator_r ange 

cfsvalrange 

text 

cftext 
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Correspondence Between C Names and FORTRAN Names 

Long Name 

FORTRAN Equivalent 

text_a 1 ignment 

cf text align 

text_bundle_index 

c f textbundix 

text_color 

cftextcolor 

text_ f orvt__index 

cftext fontix 

text_precision 

cftextprec 

vdc_extent 

cfvdcext 

vdm_text 

cfvdmtext 


G,4. FORTRAN Interfaces to SunCGI 

Note : Although all SunCGI procedures are declared here as functions , each may also be called as 
a subroutine if the user does not want to check the returned value . 

integer function cfactvws (name) 
integer name 

integer function cfaptext (f lag, string, stringlen) 
integer flag 
character * (*) string 
integer stringlen 

integer function cfassoc (trigger , devclass, devnum) 
integer trigger 
integer devclass 
integer devnum 
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integer function cfawaitev (timeout, valid, devclass, devnum, 

1 x, y, xlist, ylist, n, val, choice, string, str inglen, 

2 message_link, rep lost, time_stainp, qstat, overflow) 


integer 

timeout 

integer 

valid 

integer 

devclass 

integer 

devnum 

integer 

x, y 

integer 

xlist (*) 

integer 

ylist (*) 

integer 

n 

real 

val 

integer 

choice 

character* (*) string 

integer 

stringlen 

integer 

message_link 

integer 

rep lost 

integer 

time_stamp 

integer 

qstat 

integer 

overflow 

integer function cfbtblpatarr (pixpat , px, py, pixtarget. 

1 rx. 

ry, ox, oy, dx, dy) 

integer 

pixpat 

integer 

px, py 

integer 

pixtarget 

integer 

rx, ry 

integer 

ox, oy 

integer 

dx, dy 

integer function cfbtblpatsouarr (pixpat , px, py, pixsource. 

1 sx. 

sy, pixtarget, rx, ry, ox, oy, dx, dy) 

integer 

pixpat 

integer 

px, py 

integer 

pixsource 

integer 

SX, sy 

integer 

pixtarget 

integer 

rx, ry 

integer 

ox, oy 

integer 

dx, dy 

integer function cfbtblsouarr (bitsource, xo, yo, xe, ye, bittarget. 

integer 

bitsource , bittarget 

integer 

xo, yo, xe, ye, xt, yt 

integer function cfcellarr (px, qx, rx, py, qy, ry, dx, dy, colorind) 

integer 

px, py 

integer 

qx, qy 

integer 

rx, ry 

integer 

dx, dy 

integer 

colorind (*) 
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integer function cfcharexpfac (efac) 
real ©fac 


integer function cfcharheight (height) 
integer height 


integer function cfcharorient (bx, by, dx, dy) 
real bx, by, dx, dy 


integer function cfcharpath (path) 
integer path 


integer function cfcharsetix (index) 
integer index 


integer function cfcharspacing (efac) 
real efac 


integer function cfcircarccent (clx, cly, c2x, c2y, c3x, c3y, rad) 
integer clx, cly, c2x, c2y, c3x, c3y 
integer rad 


integer function cfcircarccentcl (clx, cly, c2x, c2y, c3x, c3y, rad, close) 
integer clx, cly, c2x, c2y, c3x, c3y 
integer rad 
integer close 


integer function cfcircarcthree (clx, cly, c2x, c2y, c3x, c3y) 
integer clx, cly, c2x, c2y, c3x, c3y 


integer function cfcircarcthreecl (clx, cly, c2x, c2y, c3x, c3y, close) 
integer clx, cly, c2x, c2y, c3x, c3y 
integer close 


integer function cfcircle(x, y, rad) 
integer x 
integer y 
integer rad 


integer function cfclipind (f lag) 
integer flag 


integer function cfcliprect (xmin, xmax, ymin, ymax) 
integer xmin, xmax, ymin, ymax 

integer function cfclosecgi() 
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integer function cfclrcont (soft , hard, intern, extent) 
integer soft, hard 
integer intern 
integer extent 


integer function cfclrvws (name, defflag, color) 
integer name 
integer defflag 
integer color 


integer function cfcotabl© (istart , ra, ga, ba, n) 
integer istart 
integer ra(*) , ga(*), ba(*) 
integer n 


integer function cfdaevents (devclass , devnum) 
integer devclass 
integer devnum 


integer function cfdeactvws (name) 
integer name 


integer function cfdewpt (name, xbot, ybot, xtop, ytop) 
integer name 

integer xbot, ybot, xtop, ytop 


integer function cfdissoc (trigger , devclass, devnum) 
integer trigger 
integer devclass 
integer devnum 


integer function cfdpolyline (xcoors, ycoors, n) 
integer xcoors 
integer ycoors 
integer n 


integer function cfechooff (devclass, devnum, echo) 
integer devclass 
integer devnum 
integer echo 
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integer function cfechoon (devclass, echo type, exlow, ©ylow, 

1 exup, eyup, x, y, xlist, ylist, n, val, choice, string, stringlen) 

integer devclass 
integer echotyp© 
integer ©xlow 
integer eylow 
integer exup 
integer eyup 
integer x , y 
integer xlist (*) 
integer y 1 ist ( * ) 

integer n 
real val 

integer choice 
character* (*) string 
integer stringlen 

integer function cfechoupd (echo, x, y, xlist, ylist, n, val, 

1 choice, string, stringlen) 

integer echo 

integer x, y 

integer xlist (*) 

integer ylist (*) 

integer n 

real val 

integer choice 

character* (*) string 
integer stringlen 

integer function cfelliparc (x, y , sx, sy, ex, ey, majx, rniny) 
integer x, y 

integer sx, sy 

integer ex, ey 

integer majx, miny 

integer function cfelliparccl (x, y , sx, sy, ex, ©y, majx, miny, close) 
integer x, y 

integer sx, sy 

integer ex, ey 

integer majx, miny 
integer close 

integer function cfellipse(x, y, majx, miny) 
integer x, y 

integer majx, miny 

integer function cfenovents (devclass, devnum) 
integer devclass 

integer devnum 
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integer function cffixedfont (index) 
integer index 

integer function cfflareabundix (index) 
integer index 


integer function cfflcolor (color) 
integer color 


integer function cf f lusheventqu () 


integer function cfgetlastreqinp (devclass, devnum, valid, 

1 x, y, xlist, ylist, n, val, choice, string, stringlen) 

integer devclass 
integer devnum 
integer valid 
integer x , y 
integer xlist (*) 
integer ylist (*) 
integer n 
real val 

integer choice 
character* (*) string 
integer stringlen 


integer function cfhardrst() 

integer function cfhatchix (index) 
integer index 


integer function cf init lid (devclass , devnum, x, y, xlist, ylist, n, val, 
1 choice, string, stringlen) 


integer 

devclass 

integer 

devnum 

integer 

x, y 

integer 

xlist (*) 

integer 

ylist (*) 

integer 

n 

real 

val 

integer 

choice 

character 

*(*) string 

integer 

stringlen 


integer function cfinitreq (devclass, devnum) 
integer devclass 
integer devnum 
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integer function cfintstyle (istyl©, perimvis) 
integer istyl© 
integer perimvis 

integer function cf Incolor (index) 
integer index 

integer function cf lnendstyle (ttyp) 
integer ttyp 

integer function cf lntype (ttyp) 
integer ttyp 

integer function cflnwidth (index) 
real index 

integer function cf lnwidthspecmode (mode) 
integer mode 

integer function cfmkco lor (index) 
integer index 

integer function cfmksize (index) 
real index 

integer function cfmksizespecmode (mode) 
integer mode 

integer function cfmktype (ttyp) 
integer ttyp 

integer function cfopencgi() 
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integer function cfopenvws (name, screenname, screenlen, 

1 windowname, windowlen, windowfd, retained, dd, 

2 cmapsiz©, cmapnam©, cmaplen, flags, ptr, noargs) 
integer name 

character* (*) screenname 
integer screen len 
character* (*) windowname 
integer windowlen 
integer windowfd 
integer retained 
integer dd 
integer cmapsiz© 
integer cmapname ( * ) 
integer cmaplen 
integer flags 
character* (*) ptr 
integer noargs 

integer function cfpatix (index) 
integer index 

integer function cfpatrefpt (x, y) 
integer x, y 

integer function cfpatsize (dx, dy) 
integer dx, dy 

integer function cfpatt able (index, m, n, colorind) 
integer index 
integer m, n 
integer colorind 

integer function cfperimco lor (index) 
integer index 

integer function cfperimtype (ttyp) 
integer ttyp 

integer function cfperimwidth (index) 
real index 

integer function cfpixarr(px, py, m, n, colorind) 
integer px, py 
integer m, n 
integer colorind (*) 
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integer function cfpolygon (xcoors, ycoors, n) 
integer xcoors 
integer ycoors 
integer n 


integer function cfpolyline (xcoors, ycoors, n) 
integer xcoors 
integer ycoors 
integer n 


integer function cfpolylnbundlx (index) 
integer index 


integer function cfpolymarker (xcoors, ycoors, n) 
integer xcoors 
integer ycoors 
integer n 

integer function cfpolymkbundix (index) 
integer index 


integer function cfppolyline (xcoors, ycoors, n, flag) 
integer flag 


integer function cfqasfs(n, num, vals) 
integer n 
integer num(*) 
integer vals(*) 


integer function cfqcellarr (px, qx, 
integer px, py 

integer qx, qy 

integer rx , ry 

integer dx, dy 

integer colorind (*) 


rx, py, qy, ry, dx, dy, colorind) 


integer function cfqdevbtmp (name, map) 
integer name, map 


integer function cfqdevclass (output , input) 
integer output , input 


integer function cfqdevid (naan®, devid, stringlen) 
integer name 
character * (*) devid 
integer stringlen 
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integer function cfqf lareaatts (style, vis, hindex, pindex, b index, 

1 pstyle, pwidth, pcolor) 

integer style, vis, hindex, pindex 

integer bindex 

integer pstyle 

real pwidth 

integer pcolor 

integer function cfqinpcaps (valid, numval, numstrk, numchoice, 

1 numstr, numtrig, ev queue, asynch, coordmap, tracking, 

2 prompt, acknowledgement, trigman) 

integer valid 

integer numval 
integer numstrk 
integer numchoice 
integer numstr 
integer numtrig 
integer evqueue 
integer asynch 
integer coordmap 
integer tracking 
integer prompt 
integer acknowledgement 
integer trigman 

integer function cfqlidcaps (devclass, devnum, valid, sample, 

1 change, numassoc, trigassoc, prompt, acknowledgement, 

2 echo, classdep, str inglen, state) 
integer devclass 

integer devnum 
integer valid 
integer sample 
integer change 
integer numassoc 
integer trigassoc (*) 
integer prompt 
integer acknowledgement 
integer echo ( * ) 
character* (*) classdep 
integer stringlen 
integer state (*) 
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integer function cfqlidstatelis (devclass, devnum, valid, numloc, 

1 numval, numstrk, numchoice, numstr, numtrig, ©vent queue, 

2 asynch, coordmap, echo, tracking, prompt, acknowledgement, 

3 triggermanipulation) 


integer 

devclass 

integer 

devnum 

integer 

valid 

integer 

numloc 

integer 

numval 

integer 

numstrk 

integer 

numchoice 

integer 

numstr 

integer 

numtrig 

integer 

event queue 

integer 

asynch 

integer 

coordmap 

integer 

echo 

integer 

tracking 

integer 

prompt 

integer 

acknowledgement 

integer 

tr iggermanipu 1 at ion 


integer function cfqlnatts (style, width, color, index) 
integer style 
real width 

integer color, index 


integer function cfqmkatts (type, size, color, index) 
integer type 
real size 

integer color, index 


integer function cfqoutcap (first , last, list) 
integer first, last 
character* (*) list 

integer function cfqout f unset (level , support) 
integer level 
integer support 


integer function cfqpatatts (cindex, row, column, colorlis, x, y, dx, dy) 


integer function cfqphyscsys (name, xbase, ybase, xext, yext, xunits, yunits) 
integer name 
integer xbase, ybase 
integer xext , yext 
real xunits, yunits 
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integer function cfqtext (fontset, index, cfont, prec, efac, space, 

1 color, hgt, bx, by, ux, uy, path, halign, valign, hfac, cfac) 

integer fontset, index, cfont, prec 
real efac, space 

integer color, hgt 

real bx, by, ux, uy 

integer path, halign, valign 
real hfac, cfac 

integer function cfqtextext (string, stringlen, nextchar, 

1 conx, cony, llpx, llpy, ulpx, ulpy, urpx, urpy) 

character * (*) string 
character * ( * ) nextchar 
integer stringlen 

integer conx 

integer cony 

integer llpx 

integer llpy 

integer ulpx 

integer ulpy 

integer urpx 

integer urpy 

integer function cfqtrigcaps (trigger , valid, change, n, class, 

1 assoc, numassoc, maxassoc, prompt, acknowledgement, 

1 name, namelen, description, desclen) 

integer trigger 

integer valid 

integer change 

integer n 

integer class 

integer assoc(^) 

integer numassoc 

integer maxassoc 

integer prompt 

integer acknowledgement 
character* (*) name 
integer namelen 

character* (*) description 
integer desclen 

integer function cfqtrigstate (trigger , valid, state, n, class, assoc) 
integer trigger 

integer valid 

integer state 

integer n 

integer class (*) 

integer assoc (*) 

integer function cfqvdctype (type) 
integer type 
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integer function c frect angle (xbot, ybot, xtop, ytop) 
integer xbot, ybot, xtop, ytop 


integer function cfrelidev (devclass, devnum) 
integer devclass 
integer devnum 


integer function cfreqinp (devclass, devnum, timeout, valid, sample, 

1 trigger, x, y, xlist, ylist, n, val, choice, string, str inglen) 


integer 

devclass 

integer 

devnum 

integer 

timeout 

integer 

valid 

integer 

x, y 

integer 

xlist (*) 

integer 

ylist (*) 

integer 

n 

real 

val 

integer 

choice 

character 

* (*) string 

integer 

stringlen 

integer 

trigger 


integer function cfrsttodefs (name) 
integer name 


integer function cfsampinp (devclass, devnum, valid, x, y, 
1 xlist, ylist, n, val, choice, string, stringlen) 


integer 

devclass 

integer 

devnum 

integer 

valid 

integer 

x, y 

integer 

xlist (*) 

integer 

ylist (*) 

integer 

n 

real 

val 

integer 

choice 

character 

*(*) string 

integer 

stringlen 


integer function cfsaspsouf lags (fval , fnum, n) 
integer fval ( & ) , fnum( fi ) , n 


integer function cfsdefatrigassoc (devclass, devnum) 
integer devclass 
integer devnum 
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integer function cfsdrawmod© (visibility, source, destination, combination) 
integer v i s ib i 1 i ty 

integer source 
integer destination 
integer combination 


integer function cfselectf lushevenqu (devclass, devnum) 
integer devclass 
integer devnum 


integer function cfserrwarnmk (action) 
integer action 


integer function cfsgldrawmode (combination) 
integer combination 


integer function cfsinitval (devclass, devnum, x, y, 
1 val , choice, string, stringlen) 


integer 

devclass 

integer 

devnum 

integer 

x, y 

integer 

xlist (*) 

integer 

ylist (*) 

integer 

n 

real 

val 

integer 

choice 

character 

* (*) string 

integer 

stringlen 


xlist, ylist. 


n. 


integer function cfsupsig (sig_function) 
integer sig_ function 

external sig_f unction 


integer function cfsvalrange (devnum, mn, mx) 
integer devnum 
real mn, mx 


integer function cftext(x, y, string, stringlen) 
integer x 
integer y 
character * (*) string 
integer stringlen 

integer function cf text align (halign, valign, hcalind, vcalind) 
integer halign 
integer valign 
real hcalind, vcalind 
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integer function cftextbundix (index) 
integer index 

integer function cftextcolor (index) 
integer index 

integer function cftextfontix (index) 
integer index 

integer function cftextprec (ttyp) 
integer ttyp 

integer function cfvdcext (xbot , ybot, xtop, ytop) 
integer xbot, ybot, xtop, ytop 

integer function cfvdmtext(x, y, flag, string, stringlen) 
integer x 
integer y 
integer flag 
character* (*) string 
integer stringlen 

integer function vqdrawmode (visibility, source, destination, combination) 
integer visibility 
integer source 
integer destination 
integer combination 

integer function vqfpixarr (px, py, m, n, colorind) 
integer px, py 
integer m, n 
integer colorind (*) 


G-20 


Revision A of 15 May 1985 



Index 


A 

activate_vws, 2-5 
ANSI, 1-1 
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bitblt_pattern_array, 3-14 
bitblt_patterned_source_array, 3-14 
bitblt_source_array, 3-13 
bundle table, 4-2 
bundled attributes, 4-2 thru 4-4 
Cdefbundix, 4-3 
Csaspsouflags, 4-2 
define_bundle_index, 4-3 
set_aspect_source_ flags, 4-2 
bundles, 4-2 
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Cactvws, 2-5 
Captext, 3-11 
Cassoc, 5-5 
Cawaitev, 5-13 
Cbtblpatarr, 3-14 
Cbtblpatsouarr, 3-14 
Cbtblsouarr, 3-13 
Ccellarr, 3-12 
Ccharexpfac, 4-16 
Ccharheight, 4-17 
Ccharorientation, 4-18 
Ccharpath, 4-18 
Ccharsetix, 4-15 
Cchar spacing, 4-16 
Ccircarccent, 3-6 
Ccircarccentcl, 3-7 
Ccircarcthree, 3-8 
Ccircarcthreecl, 3-9 
Ccircle, 3-6 
Cclipind, 2-16 
Ccliprect, 2-17 
Cclosecgi, 2-6 
Cclosevws, 2-6 
Cclrcont, 2-19 
Cclrvws, 2-18 
Ccotable, 4-20 
Cdaevents, 5-12 
Cdeactvws, 2-6 
Cdefbundix, 4-3 
Cdewpt, 2-16 
Cdissoc, 5-7 
Cdpolyline, 3-2 
Cell array, 3-12 
cell_array, 3-12 
Celliparc, 3-9 
Celliparccl, 3-10 
Cell ipse, 3-9 
Cenevents, 5-12 
Cfixedfont, 4-17 
Cflareabundix, 4-9 
Cflcolor, 4-10 
Cflusheventqu, 5-4 
Cgetlastreqinp, 5-11 
CGI, 1-1 
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Cgi functions, F-3 thru F-4 
CGI tool, 2-4 

CGI type definitions, C-l thru C-9 
CGI with pixwins, F-l thru F-5 
example, F-5 
functions, F-3 thru F-4 
using cgipw, F-2 
cgipw functions 

clos©_cgi_pw, F-2 
close_pw_cgi, F-2 
open_cgi__ pw, F-l 
open_pw_cgi, F-l 

char acter_expansion_f actor, 4-16 

character_height, 4-17 

character ..orientation, 4-18 

character_path, 4-18 

character_set_index, 4-15 

character_spacing, 4-16 

Chardrst, 2-17 

Chatchix, 4-10 

Cinitlid, 5-3 

Cinitreq, 5-10 

Cintstyle, 4-9 

circle 

area of a, 3-6 
perimeter definition, 3-6 
circle, 3-6 
circular arcs 
center, 3-7 
close, 3-7 

direction of drawing, 3-7 
three-point, 3-8 
circular_arc_3pt, 3-8 
circular_arc_3pt__close, 3-9 
circular_arc_center, 3-6 
circular.arc.center.close, 3-7 
clear_control, 2-19 
clear.view.sur face, 2-18 
clip_indicator, 2-16 
clip__rectangle, 2-17 
clipping, 2-14, 2-16 
Clncolor, 4-6 
Clnendstyle, 4-5 
Clntype, 4-5 
Clnwidth, 4-6 
Clnwidthspecmode, 4-5 
close_ cgi, 2-6 
close_cgi_pw, F-2 
close_pw__cgi, F-2 
close.vws, 2-6 
Cmkcolor, 4-8 
Cmksize, 4-8 
Cmksizespecmode, 4-7 
Cmktype, 4-7 

color attributes, 4-20 thru 4-21 


color attributes, continued 
Ccotable, 4-20 
color_tabl®, 4-20 
color table, 4-6, 4-20 
color_tabl@, 4-20 

conical output primitives, 3 - 1 , 3-6 thru 3-10 
control errors, D-2 

coordinate definition errors, D-2 thru D-3 

Copencgi, 2-2 

Copenvws, 2-3 

Cpatix, 4-11 

Cpatrefpt, 4-11 

Cpatsize, 4-12 

Cpattable, 4-11 

Cperimcolor, 4-13 

Cperimtype, 4-12 

Cperimwidth, 4--13 

Cperimwidthspecmode, 4-13 

Cpixarr, 3-13 

Cpolygon, 3-3 

Cpolyline, 3-2 

Cpolylnbundix, 4-4 

Cpolymarker, 3-3 

Cpolymkbundix, 4-7 

Cppolygon, 3-4 

Cqasfs, 4-24 

Cqbtblalign, 3-16 

Cqcellarr, 3-15 

Cqdevbtmp, 3-16 

Cqdevclass, 2-8 

Cqdevid, 2-7 

Cqdrawmode, 3-18 

Cqevque, 5-15 

Cqf lareaatts, 4-22 

Cqinpcaps, 2-10 

Cqlidcaps, 2-11 

Cqlidstate, 5-14 

Cqlidstatelis, 5-14 

Cqlnatts, 4-21 

Cqmkatts, 4-21 

Cqoutcap, 2-10 

Cqoutf unset, 2-9 

Cqpatatts, 4-22 

Cqphyscsys, 2-8 

Cqpixarr, 3-16 

Cqtextatts, 4-23 

Cqt extext, 3-12 

Cqtrigcaps, 2-12 

Cqtrigstate, 5-15 

Cqvdctype, 2-9 

Crectangle, 3-5 

Crelidev, 5-4 

Creqinp, 5-11 

Crsttodefs, 2-18 

Csampinp, 5-10 
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Csaspsou flags, 4-2 
Csdefatrigassoc, 5-6 
Csdrawmode, 3-17 
Cselectf lusheventqu, 5-5 
Cserrwarnmk, 2-19 
Csgldrawmode, 3-18 
Csinitval, 5-7 
Csupsig, 2-20 
Csvalrange, 5-7 
Ctext, 3-10 
Ctextalign, 4-19 
Ctextbundix, 4-14 
Ctextcolor, 4-17 
Ctext fontix, 4-15 
Ctextprec, 4-14 
Ctrackoff, 5-9 
Ctrackon, 5-8 
current position, A-l 
Cvdcext, 2-14 
Cvdmtext, 3-11 

D 

data type definitions, C-l thru C-9 

deactivate__vws, 2-6 

define_bundle_index, 4-3 

device coordinates (see screen space), 2-13 

dev ice_ viewport, 2-16 

di sab le_e vents, 5-12 

dis joint_polyline, 3-2 

dissociate, 5-7 

drawing mode, 1-3, 3-10 

drawing modes, 3-17 thru 3-18 

E 

ellipse, 3-9, 3-9 
elliptical arcs, 3-9 
drawing of, 3-10 
el liptical_arc, 3-9 
el liptical__arc_ close, 3-10 
enable_events, 5-12 
error, 2-19 

control, 2-19 
errors 

control, D-2 

coordinate definition, D-2 thru D-3 
implementation dependent, D-7 
input, D-6 thru D-7 
output attribute, D-3 thru D-5 
output primitive, D-5 thru D-6 
possible causes of visual, D-8 thru D-10 
state, D-l thru D-2 
event functions, 5-10 thru 5-13 
event queue, 5-1, 5-7, 5-13 
overflow, 5-1 
status, 5-13 


F 

fill area attributes, 4-9 thru 4-10 
fill_area_bundle_index, 4-9 
fill_color, 4-10 
fixed_ font, 4-17 
f lush_event_ queue, 5-4 
FORTRAN interface 

function definitions, G-6 thru G-20 
function name mapping, G-3 thru G-6 
Programming Hints, G-l thru G-2 
using FORTRAN, G-l 

G 

geometrical output primitives, 3-1, 3-1 thru 3-10 
get__last_requested_ input, 5-11 
global polygon list, 3-3, 3-4 

H 

hard_reset, 2-17 
hatch, 4-10 
hatchdndex, 4-10 

i 

IC_STROKE, 5-5 

implementation dependent errors, D-7 
include files, 1-2 
initialized id, 5-3 
initializing 

activate__vws, 2-5 
Cactvws, 2-5 
Cclosecgi, 2-6 
Cclosevws, 2-6 
Cdeactvws, 2-6 
close_cgi, 2-6 
close_vws, 2-6 
Copencgi, 2-2 
Copenvws, 2-3 
deactivate_vws, 2-6 
open_cgi, 2-2 
open_vws, 2-3 
initializing SunCGI, 2-2 
initiate_request, 5-10 
input device, 5-3 

capabilities, 2-10 
current measure, 5-10 
measure, 5-1 
model, 5-1 
status, 5-13 

input device management, 5-3 thru 5-8 
input devices 

initialization, 5-3 
input errors, D-6 thru D-7 
input functions 

associate, 5-5 
await_event, 5-13 
Cassoc, 5-5 
Cawaitev, 5-13 
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input functions, continued 
Cdaevents, 5-12 
Cdissoc, 5-7 
Cenevents, 5-12 
Cf lusheventqu, 5-4 
Cgetlastreqinp, 5-11 
Cinitlid, 5-3 
Cinitreq, 5-10 
Cqevque, 5-15 
Cqlidstate, 5-14 
Cqlidstatelis, 5-14 
Cqtrigstate, 5-15 
Crelidev, 5-4 
Creqinp, 5-11 
Csampinp, 5-10 
Csdefatrigassoc, 5-6 
Cselectf lusheventqu, 5-5 
Csinitval, 5-7 
Csvalrange, 5-7 
Ctrackoff, 5-9 
Ctrackon, 5-8 
disable.events, 5-12 
dissociate, 5-7 
enable.events, 5-12 
f lush.event .queue, 5-4 
get.last.requested.input, 5-11 
initialize.lid, 5-3 
initiate_request, 5-10 
inquire.. event.queue, 5-15 
inquire.lid.state, 5-14 
inquire.lid.state.list, 5-14 
inquire.tr igger .state, 5-15 
release.input.device, 5-4 
request.input, 5-11 
sample.input, 5-10 

select i ve_ f 1 ush.o f .even t_queue, 5- 
5 

set.de f ault.tr igger.associat ions, 
5-6 

set.initial.value, 5-7 
set.valuator.range, 5-7 
track.off, 5-9 
track_on, 5-8 
input model, 5-1 
inquire.. 

aspect.source.f lags, 4-24 
bitblt.alignments, 3-16 
cell.array, 3-15 
device.bitmap, 3-16 
device.class, 2-8 
device.identification, 2-7 
draving_mode, 3-18 
fill.area.at tributes, 4-22 
input.capabilities, 2-10 
lid_capabilities, 2-11 
line^attributes, 4-21 
marker_attributes, 4-21 
output.capabilities, 2-10 
output. function_set, 2-9 


inquire., continued 

pattern.attributes, 4-22 
physical.coordinate.system, 2-8 
pixel.array, 3-16 
text.attributes, 4-23 
text. extent, 3-12 
trigger.capabilities, 2-12 
vdc.type, 2-9 

inquire.event.queue, 5-15 
inquir@_lid.st ate, 5-14 
inquire.lid_state.list, 5-14 
inquire.tr igger .state, 5-15 
inquiry functions 

attributes, 4-21 thru 4-24 
interface negotiation, 2-7 thru 2-13 
Cqdevclass, 2-8 
Cqdevid, 2-7 
Cqinpcaps, 2-10 
Cqlidcaps, 2-11 
Cqoutcap, 2-10 
Cqoutf unset, 2-9 
Cqphyscsys, 2-8 
Cqtrigcaps, 2-12 
Cqvdctype, 2-9 
inquire.device.class, 2-8 
inquire.device.identification, 2-7 
inquire.input.capabilities, 2-10 
inquire.lid.capabilities, 2-11 
inquire.output.capabilities, 2-10 
inquire.output.function.set, 2-9 
inquire_physical_coordinate_system, 
2-8 

inquire.trigger.capabilities, 2-12 
inquire.vdc.type, 2-9 
inter ior.style, 4-9 
isotropy, 2-13 

L 

line attributes, 4-4 thru 4-6 
Clncolor, 4-6 
Clnendstyle, 4-5 
Clntype, 4-5 
Clnwidth, 4-6 
Clnwidthspecmode, 4-5 
Cpolylnbundix, 4-4 
line.color, 4-6 
line.endstyle, 4-5 
line.type, 4-5 
line.width, 4-6 

line_vidth_specification_jnode, 4-5 
polyline.bundle.index, 4-4 
line.color, 4-6 
line.endstyle, 4-5 
line.type, 4-5 
line.width, 4-6 

line_width_specification_jnode, 4-5 
linking SunCGI, 1-2 
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logical input device, 1-4 

M 

marker _co lor, 4-8 
marker _size, 4-8 

marker_ size_speci f icat ion_mode, 4-7 
marker __type, 4-7 
measure, 1-4, 5-1, 5-1 

N 

negotiation functions, 1-3 

o 

open_cgi, 2-2 
open_cgi_pw, F-l 
open_pw_cgi, F-l 
open.vws, 2-3 
option sets, 1-1 

output attribute errors, D-3 thru D-5 
output primitive errors, D-5 thru D-6 
output primitives, 1-1, 1-3, 3-1 *Arti3-18, A-2 
append^ text, 3-11 
bitblt_pattern_array, 3-14 
bitblt_patterned_ source. array, 3-14 
bitblt_source_array, 3-13 
Captext, 3-11 
Cbtblpatarr, 3-14 
Cbtblpatsouarr, 3-14 
Cbtblsouarr, 3-13 
Ccellarr, 3-12 
Ccircarccent, 3-6 
Ccircarccentcl, 3-7 
Ccircarcthree, 3-8 
Ccircarcthreecl, 3-9 
Ccircle, 3-6 
Cdpolyline, 3-2 
cell_array, 3-12 
Celliparc, 3-9 
Celliparccl, 3-10 
Cell ipse, 3-9 
circle, 3-6 

circular_arc_3pt, 3-8 

circular_arc_3pt_close, 3-9 

circular_arc_ center, 3-6 

circular_arc_center_close, 3-7 

conical, 3 - 1 , 3-6 thru 3-10 

Cpixarr, 3-13 

Cpolygon, 3-3 

Cpolyline, 3-2 

Cpolymarker, 3-3 

Cppolygon, 3-4 

Cqbtblalign, 3-16 

Cqcellarr, 3-15 

Cqdevbtmp, 3-16 

Cqdrawmode, 3-18 

Cqpixarr, 3-16 

Cqtextext, 3-12 
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Crectangle, 3-5 
Csdrawmode, 3-17 
Csgldrawmode, 3-18 
Ctext, 3-10 
Cvdmtext, 3-11 
disjoint_polyline, 3-2 
drawing modes, 3-17 thru 3-18 
ellipse, 3-9 
elliptical_arc, 3-9 
elliptical_arc_close, 3-10 
geometrical, 3-1 thru 3-10 
inquire_bitblt_alignments, 3-16 
inquire_cell_array, 3-15 
inquire_device_bitmap, 3-16 
inquire_drawing_mode, 3-18 
inquire_pixel_array, 3-16 
inquire_text_extent, 3-12 
partial_polygon, 3-4 
pixel_array, 3-13 
polygon, 3-3 
polygonal, $-1, 3-1 thru 3-6 
polyline, 3-2 
polymarker, 3-3 
raster, 3-10 thru 3-17 
rectangle, 3-5 
set_drawing_mode, 3-17 
set_global_drawing_mode, 3-18, 3-18 
text, 3-10 
vdnutext, 3-11 

p 

partial_polygon, 3-4 
pattern, 4-10 

reference point, 4-12 
pattern attributes, 4-10 thru 4-12 
Chatchix, 4-10 
Cpatix, 4-11 
Cpatrefpt, 4-11 
Cpatsize, 4-12 
Cpattable, 4-11 
hatch_index, 4-10 
pattern_index, 4-11 
pattern_reference_point, 4-11 
pattern_size, 4-12 
patter notable, 4-11 
pattern_index, 4-11 
pattern_reference_point, 4-11 
pattern_size, 4-12 
pattern.table, 4-11 
perimeter 

endstyle, 4-13 

perimeter attributes, 4-12 thru 4-14 
Cperimcolor, 4-13 
Cperimtype, 4-12 
Cperimwidth, 4-13 
Cperimwidthspecmode, 4-13 
perimeter_color, 4-13 
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perimeter attributes, continued 
per imet er_type, 4-12 
per imeter_width, 4-13 

per imeter_width__specif ication_mode, 
4-13 

perimeter visibility, 4-9 
per im©ter_color, 4-13 
perimeter_type, 4-12 
per imeter. width, 4-13 

per imeter__width_speci f icat ion_jnode, 

4-13 

pie chart, 3-7 
pixel_array, 3-13, 3-13 
pixwins with CGI, F-l thru F-5 
example, F-5 
functions, F-3 thru F-4 
using cgipw, F-2 
point 

drawing a, 3-6 
polygon, 3-3 

with holes, 3-4 
with undrawn edge(s), 3-4 
polygonal primitives, 3 - 1 , 3-1 thru 3-6 
polyline, 3-2 

polyline_bundle_index, 4-4 
polymarker, 3-3 
polymarker attributes, 4-6 thru 4-8 
Cmkcolor, 4-8 
Cmksize, 4-8 
Cmksizespecmode, 4-7 
C ink type, 4-7 
Cpolymkbundix, 4-7 
marker_color, 4-8 
marker_size, 4-8 

marker _s ize_speci f icat ion_mode, 4- 
7 

marker_type, 4-7 
polymarker_bundle_ index, 4-7 
polymarker_bundle_ index, 4-7 

R 

raster primitives, 3 - 1 , 3-10 thru 3-17 
rectangle, 3-5 
release_input_ device, 5-4 
request register, 5-10, 5-11 
request_input, 5-11 
reset_to_defaults, 2-18 

s 

sample_input, 5-10 
screen space, 1-3, 1-3, 2-13, 2-20 
definition, 2-16 

select ive_ f lush__o f_event_queue, 5- 5 
set_aspect_source_ flags, 4-2 
set_default_trigger_associations, 5-6 
set_drawing_mode, 3-17 


set_error_warning_mask, 2-19 
set_global_drawing_mode, 3-18, 3-18 
sat_initial__value, 5-7 
s@t_up_sigwinch, 2-20 
set_valuator_range, 5-7 
SIGWINCH, 1-3, 2-20 
solid object attributes, 4-8 thru 4-14 
Cf lareabundix, 4-9 
Cflcolor, 4-10 
Cintstyle, 4-9 

fill__area_Jbundle_index, 4-9 
£ill__color, 4-10 
interior_style, 4-9 
specified device, 2-11 
state errors, D-l thru D-2 
status inquiries, 5-13 thru 5-15 
Sun Workstation, 2-7 
SunCGI, 1-1 

with window system, 2-20 

T 

text attributes, 4-14 thru 4-20 
Ccharexpfac, 4-16 
Ccharheight, 4-17 
Ccharorientation, 4-18 
Ccharpath, 4-18 
Ccharsetix, 4-15 
Ccharspacing, 4-16 
Cfixedfont, 4-17 

character _expansion_factor, 4-16 
character__height, 4-17 
character ^orientation, 4-18 
char act er_path, 4-18 
character_set_index, 4-15 
character_spacing, 4-16 
Ctextalign, 4-19 
Ctextbundix, 4-14 
Ctextcolor, 4-17 
Ctextfontix, 4-15 
Ctextprec, 4-14 
fixed_font, 4-17 
text_alignment, 4-19 
text_bundle_ index, 4-14 
text_ color, 4-17 
text_font_index, 4-15 
text_precision, 4-14 
text precision, 3-11 

detailed definition, 4-14 
text, 3-10 

appended, 3-11 
textual ignment, 4-19 
text, 3-10 

text_bundle_index, 4-14 
text_color, 4-17 
text_font_index, 4-15 
text_precision, 4-14 
textured line, 4-5 
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track, 5-1, 5-8, 5-9 
track_o£f, 5-9 
track__on, 5-8 
tracking, 5-8 thru 5-9 
trigger, 1-4, 2-10, 5-1, 5-6 
activation, 5-1 
Trigger 

Capabilities, 2-12 
trigger 

interaction with stroke device, 5-6 
status, 5-13 

type definitions, C-l thru C-9 

u 

unsupported CGI functions, B-l thru B-2 
using SuoCGI, 1-2 

v 

VDC Space, 1-3, 1-3, 2-13, 2-13, 2-20 
vdc_extent, 2-14 
vdnLjtext, 3-11 
view surface, 2-1 

clear control, 2-19 
clearing, 2-18 
default states, 2-5 
view surface control, 2-13 thru 2-19 
Cclipind, 2-16 
Ccliprect, 2-17 
Cclrcont, 2-19 
Cclrvws, 2-18 
Cdewpt, 2-16 
Chardrst, 2-17 
clear_control, 2-19 
clear_view_sur face, 2-18 
clip_indicator, 2-16 
clip_rectangle, 2-17 
Crsttodefs, 2-18 
Cserrwarnmk, 2-19 
Cvdcext, 2-14 
device_viewport, 2-16 
hard_reset, 2-17 
reset_to_defaults, 2-18 
set_error_warning_mask, 2-19 
vdc_extent, 2-14 
view surfaces, 2-5 
active, 1-3 
initializing, 2-3 
multiple, 1-3, 2-3 
visual errors 

possible causes, D-8 thru D-10 

w 

window system 

Csupsig, 2-20 
set_up_sigwinch, 2-20 
using SunCGI with, 2-20 
windows 


windows, continued 
nonretained, 2-4 
retained, 2-4 

world coordinates (see VDC Space), 2-13 

x 

X3H3, 1-1 
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